github
/
micropython
mirror of https://github.com/micropython/micropython.git
1
0
Fork 0
Code Issues Projects Releases Wiki Activity
Browse Source

docs: Remove sphinx_selective_exclude, it's no longer used.

pull/4194/merge
Damien George 6 years ago
parent
b3e013f60e
commit
d1adfee251
7 changed files with 0 additions and 320 deletions
Whitespace
Show all changes Ignore whitespace when comparing lines Ignore changes in amount of whitespace Ignore changes in whitespace at EOL
Split View
Diff Options
Show Stats Download Patch File Download Diff File
  1. 3
      docs/conf.py
  2. 25
      docs/sphinx_selective_exclude/LICENSE
  3. 138
      docs/sphinx_selective_exclude/README.md
  4. 0
      docs/sphinx_selective_exclude/__init__.py
  5. 45
      docs/sphinx_selective_exclude/eager_only.py
  6. 75
      docs/sphinx_selective_exclude/modindex_exclude.py
  7. 34
      docs/sphinx_selective_exclude/search_auto_exclude.py

3
docs/conf.py
View File

@ -50,9 +50,6 @@ extensions = [
'sphinx.ext.intersphinx',
'sphinx.ext.todo',
'sphinx.ext.coverage',
'sphinx_selective_exclude.modindex_exclude',
'sphinx_selective_exclude.eager_only',
'sphinx_selective_exclude.search_auto_exclude',
]
# Add any paths that contain templates here, relative to this directory.

25
docs/sphinx_selective_exclude/LICENSE
View File

@ -1,25 +0,0 @@
Copyright (c) 2016 by the sphinx_selective_exclude authors.
All rights reserved.
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
OWNER 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.

138
docs/sphinx_selective_exclude/README.md
View File

@ -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.

0
docs/sphinx_selective_exclude/__init__.py
View File

45
docs/sphinx_selective_exclude/eager_only.py
View File

@ -1,45 +0,0 @@
#
# This is a Sphinx documentation tool extension which makes .only::
# directives be eagerly processed early in the parsing stage. This
# makes sure that content in .only:: blocks gets actually excluded
# as a typical user expects, instead of bits of information in
# these blocks leaking to documentation in various ways (e.g.,
# indexes containing entries for functions which are actually in
# .only:: blocks and thus excluded from documentation, etc.)
# Note that with this extension, you may need to completely
# rebuild a doctree when switching builders (i.e. completely
# remove _build/doctree dir between generation of HTML vs PDF
# documentation).
#
# This extension works by monkey-patching Sphinx core, so potentially
# may not work with untested Sphinx versions. It tested to work with
# 1.2.2 and 1.4.2
#
# Copyright (c) 2016 Paul Sokolovsky
# Based on idea by Andrea Cassioli:
# https://github.com/sphinx-doc/sphinx/issues/2150#issuecomment-171912290
# Licensed under the terms of BSD license, see LICENSE file.
#
import sphinx
from docutils.parsers.rst import directives
class EagerOnly(sphinx.directives.other.Only):
def run(self, *args):
# Evaluate the condition eagerly, and if false return no nodes right away
env = self.state.document.settings.env
env.app.builder.tags.add('TRUE')
#print(repr(self.arguments[0]))
if not env.app.builder.tags.eval_condition(self.arguments[0]):
return []
# Otherwise, do the usual processing
nodes = super(EagerOnly, self).run()
if len(nodes) == 1:
nodes[0]['expr'] = 'TRUE'
return nodes
def setup(app):
directives.register_directive('only', EagerOnly)

75
docs/sphinx_selective_exclude/modindex_exclude.py
View File

@ -1,75 +0,0 @@
#
# This is a Sphinx documentation tool extension which allows to
# exclude some Python modules from the generated indexes. Modules
# are excluded both from "modindex" and "genindex" index tables
# (in the latter case, all members of a module are excluded).
# To control exclusion, set "modindex_exclude" variable in Sphinx
# conf.py to the list of modules to exclude. Note: these should be
# modules (as defined by py:module directive, not just raw filenames).
# This extension works by monkey-patching Sphinx core, so potentially
# may not work with untested Sphinx versions. It tested to work with
# 1.2.2 and 1.4.2
#
# Copyright (c) 2016 Paul Sokolovsky
# Licensed under the terms of BSD license, see LICENSE file.
#
import sphinx
#org_PythonModuleIndex_generate = None
org_PyObject_add_target_and_index = None
org_PyModule_run = None
EXCLUDES = {}
# No longer used, PyModule_run() monkey-patch does all the job
def PythonModuleIndex_generate(self, docnames=None):
docnames = []
excludes = self.domain.env.config['modindex_exclude']
for modname, (docname, synopsis, platforms, deprecated) in self.domain.data['modules'].items():
#print(docname)
if modname not in excludes:
docnames.append(docname)
return org_PythonModuleIndex_generate(self, docnames)
def PyObject_add_target_and_index(self, name_cls, sig, signode):
if hasattr(self.env, "ref_context"):
# Sphinx 1.4
ref_context = self.env.ref_context
else:
# Sphinx 1.2
ref_context = self.env.temp_data
modname = self.options.get(
'module', ref_context.get('py:module'))
#print("*", modname, name_cls)
if modname in self.env.config['modindex_exclude']:
return None
return org_PyObject_add_target_and_index(self, name_cls, sig, signode)
def PyModule_run(self):
env = self.state.document.settings.env
modname = self.arguments[0].strip()
excl = env.config['modindex_exclude']
if modname in excl:
self.options['noindex'] = True
EXCLUDES.setdefault(modname, []).append(env.docname)
return org_PyModule_run(self)
def setup(app):
app.add_config_value('modindex_exclude', [], 'html')
# global org_PythonModuleIndex_generate
# org_PythonModuleIndex_generate = sphinx.domains.python.PythonModuleIndex.generate
# sphinx.domains.python.PythonModuleIndex.generate = PythonModuleIndex_generate
global org_PyObject_add_target_and_index
org_PyObject_add_target_and_index = sphinx.domains.python.PyObject.add_target_and_index
sphinx.domains.python.PyObject.add_target_and_index = PyObject_add_target_and_index
global org_PyModule_run
org_PyModule_run = sphinx.domains.python.PyModule.run
sphinx.domains.python.PyModule.run = PyModule_run

34
docs/sphinx_selective_exclude/search_auto_exclude.py
View File

@ -1,34 +0,0 @@
#
# This is a Sphinx documentation tool extension which allows to
# automatically exclude from full-text search index document
# which are not referenced via toctree::. It's intended to be
# used with toctrees conditional on only:: directive, with the
# idea being that if you didn't include it in the ToC, you don't
# want the docs being findable by search either (for example,
# because these docs contain information not pertinent to a
# particular product configuration).
#
# This extension depends on "eager_only" extension and won't work
# without it.
#
# Copyright (c) 2016 Paul Sokolovsky
# Licensed under the terms of BSD license, see LICENSE file.
#
import sphinx
org_StandaloneHTMLBuilder_index_page = None
def StandaloneHTMLBuilder_index_page(self, pagename, doctree, title):
if pagename not in self.env.files_to_rebuild:
if pagename != self.env.config.master_doc and 'orphan' not in self.env.metadata[pagename]:
print("Excluding %s from full-text index because it's not referenced in ToC" % pagename)
return
return org_StandaloneHTMLBuilder_index_page(self, pagename, doctree, title)
def setup(app):
global org_StandaloneHTMLBuilder_index_page
org_StandaloneHTMLBuilder_index_page = sphinx.builders.html.StandaloneHTMLBuilder.index_page
sphinx.builders.html.StandaloneHTMLBuilder.index_page = StandaloneHTMLBuilder_index_page
Write Preview
Loading…
Cancel
Save