sphinx-highlights¶

Sphinx extension to display a selection of highlights from a Python library.

Docs
Tests
PyPI
Anaconda
Activity
QA
Other

Installation¶

python3 -m pip install sphinx-highlights --user

First add the required channels

conda config --add channels https://conda.anaconda.org/conda-forge
conda config --add channels https://conda.anaconda.org/domdfcoding

Then install

conda install sphinx-highlights

python3 -m pip install git+https://github.com/sphinx-toolbox/sphinx-highlights@master --user

Enable seed_intersphinx_mapping by adding the following to the extensions variable in your conf.py:

extensions = [
    ...
    'seed_intersphinx_mapping',
    ]

For more information see https://www.sphinx-doc.org/en/master/usage/extensions#third-party-extensions .

Contents¶

Usage¶

sphinx-highlights provides a single directive:

.. api-highlights::¶

Shows 4 random highlights of the library.

The objects to include in the highlights are given in the body of the directive. For example:

.. api-highlights::

    domdf_python_tools.stringlist.StringList
    domdf_python_tools.testing.check_file_regression
    domdf_python_tools.paths.PathPlus
    domdf_python_tools.iterative.groupfloats

More than four objects can be listed. A random selection of those will be chosen when the documentation is built.

:module: (string)¶

The parent module of all of these objects.

Allows the module name to be replaced with a dot (.). For example:

.. api-highlights::
    :module: domdf_python_tools

    .stringlist.StringList

:colours: (Comma- or space-separated list of strings.)¶: The colours to use for the panel headers. Choose from “blue”, “green”, “red”, or “orange”.

Default “blue”.

Changed in version 0.2.0: If more than four colours are provided four will be chosen at random.

:classes: (Comma- or space-separated list of strings.)¶: The classes to use for the panels.

Default col-xl-6 col-lg-6 col-md-12 col-sm-12 col-xs-12 p-2.

Customising the colours¶

By default the only colours available are:

blue

green

red

orange

Additional colours can be created by adding your own custom CSS to Sphinx:

div.sphinx-highlights div.highlight-purple div.card-header {
    background-color: #B452CD;
}

where purple is the name of the colour to use in the colours option.

purple

Demo¶

Highlights¶

stringlist.StringList

StringList(
  iterable: Iterable[String] = (),
  convert_indents: bool = False,
  )

A list of strings that represent lines in a multiline string.

See more in domdf_python_tools.stringlist.

utils.head()

head(
  obj: Union[Tuple, List, DataFrame, Series, String, HasHead],
  n: int = 10,
  ) -> Optional[str]

Returns the head of the given object.

See more in domdf_python_tools.utils.

paths.PathPlus

PathPlus(*args, **kwargs)

Subclass of pathlib.Path with additional methods and a default encoding of UTF-8.

See more in domdf_python_tools.paths.

iterative.groupfloats()

groupfloats(
  iterable: Iterable[float],
  step: float = 1,
  ) -> Iterable[Tuple[float, ...]]

Returns an iterator over the discrete ranges of values in iterable.

See more in domdf_python_tools.iterative.

See another example in the documentation for domdf_python_tools, which uses the ReadTheDocs Sphinx Theme.

API Reference¶

Sphinx extension to display a selection of highlights from a Python library.

Classes:

SphinxHighlightsDirective(name, arguments, …)

Provides the api-highlights directive.

Functions:

`copy_assets`(app[, exception])	Copy asset files to the output.
`format_parameter`(param)	Format an `inspect.Parameter`, for insertion into the highlight panel.
`format_signature`(obj)	Format the signature of the given object, for insertion into the highlight panel.
`get_random_sample`(items)	Returns four random elements from `items`.
`setup`(app)	Setup `sphinx_highlights`.

class SphinxHighlightsDirective(name, arguments, options, content, lineno, content_offset, block_text, state, state_machine)[source]¶

Bases: SphinxDirective

Provides the api-highlights directive.

Methods:

`delimited_get`(option, default)	Returns the value of the option with the given name, splitting the input at commas, semicolons and spaces.
`run`()	Create the highlights node.
`run_generic`()	Generate generic reStructuredText output.
`run_html`()	Generate output for `HTML` builders.

delimited_get(option, default)[source]¶

Returns the value of the option with the given name, splitting the input at commas, semicolons and spaces.

Parameters

option (str) – The option name.
default (str) – The default value, as a string separated by commas, spaces or semicolons.

Return type

Iterator[str]

run()[source]¶

Create the highlights node.

Return type: List[Node]

run_generic()[source]¶

Generate generic reStructuredText output.

Return type: List[Node]

run_html()[source]¶

Generate output for HTML builders.

Return type: List[Node]

copy_assets(app, exception=None)[source]¶

Copy asset files to the output.

Parameters

app (Sphinx) – The Sphinx application.
exception (Optional[Exception]) – Any exception which occurred and caused Sphinx to abort. Default None.

format_parameter(param)[source]¶

Format an inspect.Parameter, for insertion into the highlight panel.

Parameters: param (Parameter)
Return type: str
Returns: The reStructuredText string.

format_signature(obj)[source]¶

Format the signature of the given object, for insertion into the highlight panel.

Parameters: obj (Union[type, FunctionType])
Return type: StringList
Returns: A list of reStructuredText lines.

get_random_sample(items)[source]¶

Returns four random elements from items.

Parameters: items (Iterable[~_T])
Return type: List[~_T]

setup(app)[source]¶

Setup sphinx_highlights.

Parameters: app (Sphinx) – The Sphinx application.
Return type: SphinxExtMetadata

Downloading source code¶

The sphinx-highlights source code is available on GitHub, and can be accessed from the following URL: https://github.com/sphinx-toolbox/sphinx-highlights

If you have git installed, you can clone the repository with the following command:

git clone https://github.com/sphinx-toolbox/sphinx-highlights

Cloning into 'sphinx-highlights'...
remote: Enumerating objects: 47, done.
remote: Counting objects: 100% (47/47), done.
remote: Compressing objects: 100% (41/41), done.
remote: Total 173 (delta 16), reused 17 (delta 6), pack-reused 126
Receiving objects: 100% (173/173), 126.56 KiB | 678.00 KiB/s, done.
Resolving deltas: 100% (66/66), done.

Alternatively, the code can be downloaded in a ‘zip’ file by clicking:

Clone or download –> Download Zip

Downloading a ‘zip’ file of the source code¶

Building from source¶

The recommended way to build sphinx-highlights is to use tox:

tox -e build

The source and wheel distributions will be in the directory dist.

If you wish, you may also use pep517.build or another PEP 517-compatible build tool.

License¶

sphinx-highlights is licensed under the MIT License

A short and simple permissive license with conditions only requiring preservation of copyright and license notices. Licensed works, modifications, and larger works may be distributed under different terms and without source code.

Permissions	Conditions	Limitations
Commercial use Modification Distribution Private use	License and copyright notice	Liability Warranty

See more information on choosealicense.com ➩

Copyright (c) 2021 Dominic Davis-Foster

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM,
DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR
OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE
OR OTHER DEALINGS IN THE SOFTWARE.

View the Function Index or browse the Source Code.

Browse the GitHub Repository