Compare doc/conf.py after merge at c9480f994 to what it was at 2ee033838.
It loses the modification from #8716 (merged at 38c614347) and thus
reverts doc/conf.py to former font config using mathpazo.
The latex macros from sphinx.sty were already partitioned into
successive sections. The file sphinx.sty is split into multiple
files in concordance with this pre-existing sectioning.
The files are loaded via \input. File extension is .sty not .tex
to not confuse the Makefile.
As discussed in #7879, the default style of line numbers for code
blocks in HTML output becames 'inline' by default. And 'table' style
is now deprecated and will be removed in Sphinx-6.0.
Add new configuration variables: `html_permalinks` and
`html_permalinks_icon`.
This refines the settings around HTML permalinks.
* html_add_permalinks
* Deprecated.
* html_permalinks
* Enable or disable permalinks feature.
* html_permalinks_icon
* Change the icon for permalinks
Prior to this the depth of the bookmarks is too low, one does not even
get to see for example what are the built-in extensions offered by
Sphinx.
Similarly the LaTeX created table of contents has not enough depth.
Dozens of contiguous pages from our documentation get only a single
link, it is very hard for newcomer to get some feeling of the scope of
Sphinx. With a more detailed table of contents (be it inside the PDF or
via the collapsable bookmark panel of PDF viewer) learning Sphinx is
easier.
To embed the external favicon and logo image, this adds new template
variable `favicon_url` and `logo_url` that point the external URL or
relative path for the favicon/logo file from current file. It helps to
use it on template files.
The anchors for viewcode was generated in the reading phase only if
supported builder is used. It causes anchors are missing on the
incremental build after the build for non supported builder.
This introduces `viewcode_anchor` node to insert the anchor even if non
supported builders. They will be converted to the anchor tag in the
resolving phase for supported builders. Or, they will be removed for
non supported builders.
I missed that there are actually two sections explaining extensions in the docs and just saw the examples based one. This lead to me thinking "kind of lousy documentation, but that's probably par for the course". Would there have been a pointer to the detailed extension API description it would have saved me hours of guesswork.
These attributes were used to cache checked links and avoid issuing
another web request to the same URI.
Since 82ef497a8c, links are pre-processed
to ensure uniqueness. This caching the results of checked links is no
longer useful.
This replaces times package with tgtermes and tgheros (clones of Times and
Helvetica with better LaTeX support) and the monospace font from txfonts
package (txtt). This font is better matched with Times-like fonts than
Courier clones.
The changes applies to pdflatex/platex/uplatex.
Fixes: #8711
Outside production lists, syntax "`foo:bar`" already makes it possible to
refer to the production "bar" of group "foo". This commit offers the same
feature inside production lists. Similarly to the reference syntax,
prefixing with a tilde prevents the group from being displayed.
This commit also makes it possible to use "`:bar`" to refer to production
"bar" from a production list without a group name. This is especially
useful when one has a main (unnamed) grammar and one or several named
extensions that need to refer to it.
So far, linkcheck scans all of references and images from documents, and
checks them parallel. As a result, some URL would be checked twice (or
more) by race condition.
This collects the URL via post-transforms, and removes duplicated URLs
before checking availability.
refs: #4303
To keep compatibility with the standard doctree model of docutils,
this stops to use 'default' value as a default value of the align
attribute for figure and table nodes.
This changes the structure of `highlight_options` to a dictionary that
maps language names to option dictionary. It allows to setting pygments
options for multiple languages at once.
To control the visibility of variables, ModuleDocumenter have to load
docstring of them on `get_object_members()` phase. This reimplements
it and `get_module_members()` helper to fetch docstring on earlier
phase (as ClassDocumenter does).
autodata and autoattribute directives does not show right-hand value of
the variable if its docstring contains ``:meta hide-value:`` in
info-field-list.
I'm very happy to see that the events in Sphinx have been laid out in order as they have been in this doc.
With that being said the notation I noticed was a bit odd. Some of the items in the list refer to events and as a result,
parenthesis are used to indicate the beginning and end of the parameters that the event takes.
In other items in the list, parenthesis are used for additional context for an event. The combination of some particularly very long lines,
the intermixing of comments, pseudo-code, indentation of items following a `for` or an `if` made this very difficult to read on a mobile device.
As a result, I've added whitespace, fixed a typo, reduced the length of some lines by moving them to a new line, and removed all `()` that were not
present to indicate parameters fed to a function.
The utility function movefile() was added in
677d096393 to handle existing files on
Windows. Since Python 3.3, the stdlib function os.replace() fills this
role.
This deprecates `no_docstring` argument for Documenter.add_content().
After this change, please use Documenter.get_doc() to control (suppress)
the content of the python object.
Since v2.3, Sphinx supports uplatex as an alternative of latex_engine for Japanese
docs (refs: #4186, #6841). uplatex is able to build a document without conversion
character encoding internally. It allows using unicode characters in documents.
Additionally, uplatex is compatible with platex (current default latex_engine for
Japanese docs).
This changes the default latex_engine for Japanese document to uplatex.
At present, the implementation of Documenter.get_object_members() is
only for class objects. In fact, no subclasses use it (all of them are
overriding the method).
This deprecates Documenter.get_object_members() and copies it to
ClassDocumenter.get_object_members().
This method always returns False, it is dead code. The exception
checking stopped working because Requests library wraps SSL errors in a
`requests.exceptions.SSLError` and no longer throws an
`urllib3.exceptions.SSLError`. The first argument to that exception is
an `urllib3.exceptions.MaxRetryError`.
Keep imports alphabetically sorted and their order homogeneous across
Python source files.
The isort project has more feature and is more active than the
flake8-import-order plugin.
Most issues caught were simply import ordering from the same module.
Where imports were purposefully placed out of order, tag with
isort:skip.
In #7651, autodoc stops to undecorate the functions on getting the
signature from the callables. But some kinds of decorators conceals
the correct signature because they pass through their arguments via
`(*args, **kwargs)`.
This restarts to undecorate the functions again as before #7651.
To be clear the ambiguous warning for missing-reference :ref:,
this separates the warning to missing-label and missing-caption.
To emit a warning dynamically, this also adds a new event:
`warn-missing-reference` to customize warning messages via event
handlers.
- No longer attempt to be the location for listing themes -- only Sphinx-RTD-Theme was listed here.
- Mention the classifier used when searching on PyPI.
- Emphasize sphinx-themes.org as a gallery of themes.
In #7487, SingledispatchFunctionDocumenter is merged into
FunctionDocumenter. SingledispatchMethodDocumenter is also. As a result,
They are no longer needed. So this deprecates them.
Add a new config variable; man_make_section_directory to make a
section directory on build man page. During 3.x, it defaults to
False and will be changed to True on 4.0 release.
Trailing whitespace do not have impact on the result, they are just
unused bytes. Most text editors are configured to strip trailing
whitespaces. Remove them all in one go.
Update a handful of files to use the UNIX line ending.
This postpones the evaluation of LaTeX packages via
``app.add_latex_package()`` to just before writing .tex file. That
allows extensions to add LaTeX packages during reading and resolving
phase.
