Sphinx eager ".. only::" directive and other selective rendition extensions
===========================================================================
Project home page: https://github.com/pfalcon/sphinx_selective_exclude
The implementation of ".. only::" directive in Sphinx documentation
generation tool is known to violate principles of least user surprise
and user expectations in general. Instead of excluding content early
in the pipeline (pre-processor style), Sphinx defers exclusion until
output phase, and what's the worst, various stages processing ignore
"only" blocks and their exclusion status, so they may leak unexpected
information into ToC, indexes, etc.
There's multiple issues submitted upstream on this matter:
* https://github.com/sphinx-doc/sphinx/issues/2150
* https://github.com/sphinx-doc/sphinx/issues/1717
* https://github.com/sphinx-doc/sphinx/issues/1488
* etc.
They are largely ignored by Sphinx maintainers.
This projects tries to rectify situation on users' side. It actually
changes the way Sphinx processes "only" directive, but does this
without forking the project, and instead is made as a standard
Sphinx extension, which a user may add to their documentation config.
Unlike normal extensions, extensions provided in this package
monkey-patch Sphinx core to work in a way expected by users.
eager_only
----------
The core extension provided by the package is called `eager_only` and
is based on the idea by Andrea Cassioli (see bugreports above) to
process "only" directive as soon as possible during parsing phase.
This approach has some drawbacks, like producing warnings like
"WARNING: document isn't included in any toctree" if "only" is used
to shape up a toctree, or the fact that changing a documentation
builder (html/latex/etc.) will almost certainly require complete
rebuild of documentation. But these are relatively minor issues
comparing to completely broken way "only" works in upstream Sphinx.
modindex_exclude
----------------
"only" directive allows for fine-grained conditional exclusion, but
sometimes you may want to exclude entire module(s) at once. Even if
you wrap an entire module description in "only" directive, like:
.. only: option1
.. module:: my_module
...
You will still have an HTML page generated, albeit empty. It may also
go into indexes, so will be discoverable by users, leading to less
than ideal experience. `modindex_exclude` extension is design to
resolve this issue, by making sure that any reference of a module
is excluded from Python module index ("modindex"), as well as
general cross-reference index ("genindex"). In the latter case,
any symbol belong to a module will be excluded. Unlike `eager_only`
extension which appear to have issued with "latexpdf" builder,
`modindex_exclude` is useful for PDF, and allows to get cleaner
index for PDF, just the same as for HTML.
search_auto_exclude
-------------------
Even if you exclude soem documents from toctree:: using only::
directive, they will be indexed for full-text search, so user may
find them and get confused. This plugin follows very simple idea
that if you didn't include some documents in the toctree, then
you didn't want them to be accessible (e.g. for a particular
configuration), and so will make sure they aren't indexed either.
This extension depends on `eager_only` and won't work without it.
Note that Sphinx will issue warnings, as usual, for any documents
not included in a toctree. This is considered a feature, and gives
you a chance to check that document exclusions are indeed right
for a particular configuration you build (and not that you forgot
to add something to a toctree).
Summary
-------
Based on the above, sphinx_selective_exclude offers extension to let
you:
* Make "only::" directive work in an expected, intuitive manner, using
`eager_only` extension.
* However, if you apply only:: to toctree::, excluded documents will
still be available via full-text search, so you need to use
`search_auto_exclude` for that to work as expected.
* Similar to search, indexes may also require special treatment, hence
there's the `modindex_exclude` extension.
Most likely, you will want to use all 3 extensions together - if you
really want build subsets of docimentation covering sufficiently different
configurations from a single doctree. However, if one of them is enough
to cover your usecase, that's OK to (and why they were separated into
3 extensions, to follow KISS and "least surprise" principles and to
not make people deal with things they aren't interested in). In this case,
however remember there're other extensions, if you later hit a usecase
when they're needed.
Usage
-----
To use these extensions, add https://github.com/pfalcon/sphinx_selective_exclude
as a git submodule to your project, in documentation folder (where
Sphinx conf.py is located). Alternatively, commit sphinx_selective_exclude
directory instead of making it a submodule (you will need to pick up
any project updates manually then).
Add following lines to "extensions" settings in your conf.py (you
likely already have some standard Sphinx extensions enabled):
extensions = [
...
'sphinx_selective_exclude.eager_only',
'sphinx_selective_exclude.search_auto_exclude',
'sphinx_selective_exclude.modindex_exclude',
]
As discussed above, you may enable all extensions, or one by one.
Please note that to make sure these extensions work well and avoid producing
output docs with artifacts, it is IMPERATIVE to remove cached doctree if
you rebuild documentation with another builder (i.e. with different output
format). Also, to stay on safe side, it's recommended to remove old doctree
anyway before generating production-ready documentation for publishing. To
do that, run something like:
rm -rf _build/doctrees/
A typical artificat when not following these simple rules is that content
of some sections may be missing. If you face anything like that, just
remember what's written above and remove cached doctrees.
Raw data
{
"_id": null,
"home_page": "https://github.com/pfalcon/sphinx_selective_exclude",
"name": "sphinx-selective-exclude",
"maintainer": "",
"docs_url": null,
"requires_python": "",
"maintainer_email": "",
"keywords": "sphinx,only,plugin",
"author": "Paul Sokolovsky",
"author_email": "pfalcon@users.sourceforge.net",
"download_url": "https://files.pythonhosted.org/packages/c2/07/4d6cb9dbe1b06be5caa21eed9813ac1e5ca5b29f3728be1d5e52f1cd7267/sphinx_selective_exclude-1.0.3.tar.gz",
"platform": "any",
"description": "Sphinx eager \".. only::\" directive and other selective rendition extensions\n===========================================================================\n\nProject home page: https://github.com/pfalcon/sphinx_selective_exclude\n\nThe implementation of \".. only::\" directive in Sphinx documentation\ngeneration tool is known to violate principles of least user surprise\nand user expectations in general. Instead of excluding content early\nin the pipeline (pre-processor style), Sphinx defers exclusion until\noutput phase, and what's the worst, various stages processing ignore\n\"only\" blocks and their exclusion status, so they may leak unexpected\ninformation into ToC, indexes, etc.\n\nThere's multiple issues submitted upstream on this matter:\n\n* https://github.com/sphinx-doc/sphinx/issues/2150\n* https://github.com/sphinx-doc/sphinx/issues/1717\n* https://github.com/sphinx-doc/sphinx/issues/1488\n* etc.\n\nThey are largely ignored by Sphinx maintainers.\n\nThis projects tries to rectify situation on users' side. It actually\nchanges the way Sphinx processes \"only\" directive, but does this\nwithout forking the project, and instead is made as a standard\nSphinx extension, which a user may add to their documentation config.\nUnlike normal extensions, extensions provided in this package\nmonkey-patch Sphinx core to work in a way expected by users.\n\neager_only\n----------\n\nThe core extension provided by the package is called `eager_only` and\nis based on the idea by Andrea Cassioli (see bugreports above) to\nprocess \"only\" directive as soon as possible during parsing phase.\nThis approach has some drawbacks, like producing warnings like\n\"WARNING: document isn't included in any toctree\" if \"only\" is used\nto shape up a toctree, or the fact that changing a documentation\nbuilder (html/latex/etc.) will almost certainly require complete\nrebuild of documentation. But these are relatively minor issues\ncomparing to completely broken way \"only\" works in upstream Sphinx.\n\nmodindex_exclude\n----------------\n\n\"only\" directive allows for fine-grained conditional exclusion, but\nsometimes you may want to exclude entire module(s) at once. Even if\nyou wrap an entire module description in \"only\" directive, like:\n\n .. only: option1\n .. module:: my_module\n \n ...\n\nYou will still have an HTML page generated, albeit empty. It may also\ngo into indexes, so will be discoverable by users, leading to less\nthan ideal experience. `modindex_exclude` extension is design to\nresolve this issue, by making sure that any reference of a module\nis excluded from Python module index (\"modindex\"), as well as\ngeneral cross-reference index (\"genindex\"). In the latter case,\nany symbol belong to a module will be excluded. Unlike `eager_only`\nextension which appear to have issued with \"latexpdf\" builder,\n`modindex_exclude` is useful for PDF, and allows to get cleaner\nindex for PDF, just the same as for HTML.\n\nsearch_auto_exclude\n-------------------\n\nEven if you exclude soem documents from toctree:: using only::\ndirective, they will be indexed for full-text search, so user may\nfind them and get confused. This plugin follows very simple idea\nthat if you didn't include some documents in the toctree, then\nyou didn't want them to be accessible (e.g. for a particular\nconfiguration), and so will make sure they aren't indexed either.\n\nThis extension depends on `eager_only` and won't work without it.\nNote that Sphinx will issue warnings, as usual, for any documents\nnot included in a toctree. This is considered a feature, and gives\nyou a chance to check that document exclusions are indeed right\nfor a particular configuration you build (and not that you forgot\nto add something to a toctree).\n\nSummary\n-------\n\nBased on the above, sphinx_selective_exclude offers extension to let\nyou:\n\n* Make \"only::\" directive work in an expected, intuitive manner, using\n `eager_only` extension.\n* However, if you apply only:: to toctree::, excluded documents will\n still be available via full-text search, so you need to use\n `search_auto_exclude` for that to work as expected.\n* Similar to search, indexes may also require special treatment, hence\n there's the `modindex_exclude` extension.\n\nMost likely, you will want to use all 3 extensions together - if you\nreally want build subsets of docimentation covering sufficiently different\nconfigurations from a single doctree. However, if one of them is enough\nto cover your usecase, that's OK to (and why they were separated into\n3 extensions, to follow KISS and \"least surprise\" principles and to\nnot make people deal with things they aren't interested in). In this case,\nhowever remember there're other extensions, if you later hit a usecase\nwhen they're needed.\n\nUsage\n-----\n\nTo use these extensions, add https://github.com/pfalcon/sphinx_selective_exclude\nas a git submodule to your project, in documentation folder (where\nSphinx conf.py is located). Alternatively, commit sphinx_selective_exclude\ndirectory instead of making it a submodule (you will need to pick up\nany project updates manually then).\n\nAdd following lines to \"extensions\" settings in your conf.py (you\nlikely already have some standard Sphinx extensions enabled):\n\n extensions = [\n ...\n 'sphinx_selective_exclude.eager_only',\n 'sphinx_selective_exclude.search_auto_exclude',\n 'sphinx_selective_exclude.modindex_exclude',\n ]\n\nAs discussed above, you may enable all extensions, or one by one.\n\nPlease note that to make sure these extensions work well and avoid producing\noutput docs with artifacts, it is IMPERATIVE to remove cached doctree if\nyou rebuild documentation with another builder (i.e. with different output\nformat). Also, to stay on safe side, it's recommended to remove old doctree\nanyway before generating production-ready documentation for publishing. To\ndo that, run something like:\n\n rm -rf _build/doctrees/\n\nA typical artificat when not following these simple rules is that content\nof some sections may be missing. If you face anything like that, just\nremember what's written above and remove cached doctrees.",
"bugtrack_url": null,
"license": "MIT license",
"summary": "Sphinx eager \".. only::\" directive and other selective rendition extensions",
"version": "1.0.3",
"project_urls": {
"Download": "https://github.com/pfalcon/sphinx_selective_exclude/tarball/1.0.3",
"Homepage": "https://github.com/pfalcon/sphinx_selective_exclude"
},
"split_keywords": [
"sphinx",
"only",
"plugin"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "c2074d6cb9dbe1b06be5caa21eed9813ac1e5ca5b29f3728be1d5e52f1cd7267",
"md5": "c17ba9ff85e5062a9e985b98b64b1b09",
"sha256": "76fc8fd7c24311e0ca2199a9e4db2156585acd7652a5cead98b07ef4f70f9b78"
},
"downloads": -1,
"filename": "sphinx_selective_exclude-1.0.3.tar.gz",
"has_sig": false,
"md5_digest": "c17ba9ff85e5062a9e985b98b64b1b09",
"packagetype": "sdist",
"python_version": "source",
"requires_python": null,
"size": 7227,
"upload_time": "2019-12-23T22:59:35",
"upload_time_iso_8601": "2019-12-23T22:59:35.281548Z",
"url": "https://files.pythonhosted.org/packages/c2/07/4d6cb9dbe1b06be5caa21eed9813ac1e5ca5b29f3728be1d5e52f1cd7267/sphinx_selective_exclude-1.0.3.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2019-12-23 22:59:35",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "pfalcon",
"github_project": "sphinx_selective_exclude",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"lcname": "sphinx-selective-exclude"
}
JSON
