diff options
Diffstat (limited to 'docs/sphinx_selective_exclude/README.md')
| -rw-r--r-- | docs/sphinx_selective_exclude/README.md | 138 |
1 files changed, 0 insertions, 138 deletions
diff --git a/docs/sphinx_selective_exclude/README.md b/docs/sphinx_selective_exclude/README.md deleted file mode 100644 index dab1407392..0000000000 --- a/docs/sphinx_selective_exclude/README.md +++ /dev/null @@ -1,138 +0,0 @@ -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 some 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. |