__email__: str = "*****@*****.**"
__all__ = ["ClickDirective", "nested_option", "setup"]
class NestedOption(str, enum.Enum): # noqa: SLOT000
NESTED_FULL = "full"
NESTED_SHORT = "short"
NESTED_NONE = "none"
NESTED_FULL = NestedOption.NESTED_FULL
NESTED_SHORT = NestedOption.NESTED_SHORT
NESTED_NONE = NestedOption.NESTED_NONE
click_purger = Purger("all_click")
_argument = Plural("argument", "argument(s)")
def _indent(text: str):
return '\n'.join([f" {line}" if not line.isspace() else line for line in text.split('\n')])
def _get_usage(ctx: click.Context) -> str:
"""
Alternative, non-prefixed version of 'get_usage'.
"""
formatter = ctx.make_formatter()
pieces = ctx.command.collect_usage_pieces(ctx)
formatter.write_usage(ctx.command_path, ' '.join(pieces), prefix='')
for line in content:
output.append(f"{line}")
output.set_indent_size(0)
output.blankline(ensure_single=True)
for line in content:
output.append(line)
output.blankline(ensure_single=True)
return list(output)
#: Purger to track rest-example nodes, and remove redundant ones.
rest_example_purger = Purger("all_rest_example_nodes")
@metadata_add_version
def setup(app: Sphinx) -> SphinxExtMetadata:
"""
Setup :mod:`sphinx_toolbox.rest_example`.
:param app: The Sphinx app.
.. versionadded:: 0.7.0
"""
# Hack to get the docutils tab size, as there doesn't appear to be any other way
app.setup_extension("sphinx_toolbox.tweaks.tabsize")
"""
#
# Copyright © 2020 Dominic Davis-Foster <*****@*****.**>
#
# Redistribution and use in source and binary forms, with or without modification,
# are permitted provided that the following conditions are met:
#
# * Redistributions of source code must retain the above copyright notice,
# this list of conditions and the following disclaimer.
# * Redistributions in binary form must reproduce the above copyright notice,
# this list of conditions and the following disclaimer in the documentation
# and/or other materials provided with the distribution.
#
# THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
# "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
# LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
# A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER
# OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
# EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
# PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR
# PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
# LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
# NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
# SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
#
# 3rd party
from sphinx_toolbox.utils import Purger
extras_require_purger = Purger("all_extras_requires")
assert flag(False)
with pytest.raises(AttributeError):
flag(True)
with pytest.raises(ValueError,
match="No argument is allowed; 'hello' supplied"):
flag("hello")
class MockBuildEnvironment:
pass
demo_purger = Purger("all_demo_nodes")
@pytest.mark.parametrize("nodes, output", [
([], []),
([{
"docname": "document"
}], []),
([{
"docname": "foo"
}], [{
"docname": "foo"
}]),
([{
"docname": "foo"
}, {
from sphinx.util.docutils import SphinxDirective
from typing_extensions import TypedDict
# this package
from sphinx_toolbox.utils import Purger, SphinxExtMetadata, make_github_url, metadata_add_version
__all__ = [
"pre_commit_node_purger",
"pre_commit_f8_node_purger",
"parse_hooks",
"PreCommitDirective",
"Flake8PreCommitDirective",
"setup",
]
pre_commit_node_purger = Purger("all_pre_commit_nodes")
pre_commit_f8_node_purger = Purger("all_pre_commit_f8_nodes")
def parse_hooks(hooks: str) -> List[str]:
"""
Parses the comma, semicolon and/or space delimited list of hook IDs.
:param hooks:
"""
return list(filter(None, re.split("[,; ]", hooks)))
class _BaseHook(TypedDict):
id: str # noqa: A003 # pylint: disable=redefined-builtin
from typing import List, Sequence, Tuple
# 3rd party
import tabulate
from docutils import nodes
from docutils.statemachine import StringList
from sphinx.application import Sphinx
from sphinx.ext.autodoc.importer import import_module
from sphinx.util.docutils import SphinxDirective
# this package
from sphinx_toolbox.utils import Purger, SphinxExtMetadata, metadata_add_version
__all__ = ["Flake8CodesDirective", "setup"]
table_node_purger = Purger("all_flake8_code_table_nodes")
class Flake8CodesDirective(SphinxDirective):
"""
A Sphinx directive for documenting flake8 codes.
"""
has_content: bool = True
# the fully qualified name of the flake8 plugin module
required_arguments: int = 1
def run(self) -> Sequence[nodes.Node]: # type: ignore
"""
Process the content of the directive.
__license__: str = "MIT License"
__version__: str = "0.5.0"
__email__: str = "*****@*****.**"
__all__ = [
"SphinxHighlightsDirective",
"copy_assets",
"format_parameter",
"format_signature",
"setup",
"get_random_sample",
]
_T = TypeVar("_T")
sphinx_highlights_purger = Purger("all_sphinx_highlights")
def format_parameter(param: inspect.Parameter) -> str:
"""
Format an :class:`inspect.Parameter`, for insertion into the highlight panel.
:param param:
:return: The reStructuredText string.
"""
formatted = param.name
# Add annotation and default value
if param.annotation is not inspect.Parameter.empty:
# stdlib
from typing import List
# 3rd party
from docutils import nodes
from docutils.statemachine import ViewList
from sphinx.application import Sphinx
from sphinx.config import Config
from sphinx.util.docutils import SphinxDirective
# this package
from sphinx_toolbox.utils import Purger, SphinxExtMetadata, metadata_add_version
__all__ = ["DocumentationSummaryDirective", "configure", "setup"]
summary_node_purger = Purger("all_summary_nodes")
RENEW = r"""
\makeatletter
\renewcommand{\py@release}{
\releasename\space\version
\par
\vspace{25pt}
\textup{\thesummary}
}
\makeatother
"""
RESET = r"\makeatletter\renewcommand{\py@release}{\releasename\space\version}\makeatother"
"""
Remove all redundant nodes.
:param app: The Sphinx application.
:param env: The Sphinx build environment.
:param docname: The name of the document to remove nodes for.
"""
if not hasattr(env, self.attr_name):
return
setattr(env, self.attr_name, [])
installation_node_purger = _Purger("all_installation_node_nodes")
extensions_node_purger = Purger("all_extensions_node_nodes")
class Sources(List[Tuple[str, str, Callable, Callable, Optional[Dict[str, Callable]]]]):
"""
Class to store functions that provide installation instructions for different sources.
The syntax of each entry is:
.. code-block:: python
(option_name, source_name, getter_function, validator_function, extra_options)
* ``option_name`` -- a string to use in the directive to specify the source to use,
* ``source_name`` -- a string to use in the tabs to indicate the installation source,
* ``getter_function`` -- the function that returns the installation instructions,