In Python 3, the default encoding of source files is utf-8. The encoding
cookie is now unnecessary and redundant so remove it. For more details,
see the docs:
https://docs.python.org/3/howto/unicode.html#the-string-type
> The default encoding for Python source code is UTF-8, so you can
> simply include a Unicode character in a string literal ...
Includes a fix for the flake8 header checks to stop expecting an
encoding cookie.
0. do not escape Unicode Greek letters via LaTeX math mark-up: pass them
through un-modified to LaTeX document,
1. if "fontenc" receives extra option LGR, then pdflatex will support
Unicode Greek letters (not in math), and with extra option T2A it
will support (most) Unicode Cyrillic letters.
2. for pdflatex with LGR, this will use "textalpha" LaTeX package and
"substitutefont" package to set up some automatic font substitution
to work around the unavailability of Greek with "times"
package (which is default font package chosen by Sphinx for
pdflatex), same with T2A and "substitutefont" for Cyrillic.
3. for xelatex/lualatex, set up Computer Modern Unicode as default font,
as it supports Cyrillic and Greek scripts,
4. for platex, don't do anything special as the engine already has
its default font supporting Cyrillic and Greek (even in math mode!)
Closes: #5251
Fixes: #5248
Fixes: #5247
This one is a little unusual. The current theming doc mixes user-focused
documentation with developer-focused documentation. This is confusing
and unnecessary. Resolve the issue by splitting the doc in two. The
user-focused docs are moved to the advanced section of the usage guide,
while the developer docs remain where they are, pending the addition of
a developer guide.
Signed-off-by: Stephen Finucane <stephen@that.guru>
In the `autodoc_default_options` documentation, it mentions that
`member-order` is respected; however, when setting the key-value pair in
`conf.py`, it is not. Thus, add `member-order` as one of the default
options respected in `conf.py`. Additionally, update the list of
supported options to match the example.
As the previous commit explains, it is now possible to specify arguments
to the global options in config files. This means that we can now include
the `exclude-members` option in this global configuration.
Previously, there was no point including this option because it makes no
sense without arguments. Including this option means users have the
flexibility of explicitly including which special methods they want using
(e.g.):
:special-members: __init__, __iter__
or explicitly excluding which special-members (or other members) they want
using (e.g.):
:exclude-members: __weakref__, __hash__
Previously, users could specify a *list* of flags in their config files.
The flags were directive names that would otherwise be present in the
.rst files. However, as a list, it was not possible to specify values
to those flags, which *is* possible in .rst files.
For example, in .rst you could say
:special-members: __init__, __iter__
And this would cause autodoc to generate documents for these methods that
it would otherwise ignore.
This commit changes the config option to instead accept a dictionary.
This is a dictionary whose keys can contain the same flag-names as before,
but whose values can contain the arguments as seen in .rst files.
The old list is still supported, for backwards compatibility, but the data
is transformed into a dictionary when the user's config is loaded.
- achieve hyperlinked page numbers in general index, despite xindy's
incompatibility with hyperref,
- obtain compatibility of pdflatex with xindy for documents with
Cyrillic scripts,
- use xindy by default with xelatex/lualatex because any non-ascii
character as first letter of an indexed term breaks PDF build if using
makeindex with lualatex, and produces incoherent index with xelatex.
This commit also switches off xindy logs (which were activated in parent
commits) as they are voluminous and not of immediate use to Sphinx user.
This is placed in a directory as this document will eventually be split
up. However, this is not the day to do this.
Signed-off-by: Stephen Finucane <stephen@that.guru>
cf http://pygments.org/docs/lexers/#lexers-for-various-shells
The difference with prior situation shows more in PDF output (but for
Windows example visible already in html) than in HTML with used theme. I
am not sure why ``select`` is highlighted but not ``sudo`` but this was
case already before.
This makes the section more consistent with the rest of the document.
This adds a new section to the basics guide for doctest blocks, which
are a docutils thing. It also update the default highlight language,
which is now 'default'.
Signed-off-by: Stephen Finucane <stephen@that.guru>
Finish building up this combined doc by adding the contents of the
former 'misc' document. There are no changes to the content.
Signed-off-by: Stephen Finucane <stephen@that.guru>
Continue building up this combined doc by adding the contents of the
former 'code' document. There are no changes to the content.
Signed-off-by: Stephen Finucane <stephen@that.guru>
Continue building up this combined doc by adding the contents of the
former 'para' document. There are no changes to the content.
Signed-off-by: Stephen Finucane <stephen@that.guru>
There's simply no need to artificially divide up the documentation on
directives into multiple, hard-to-navigate documents. Gather all
documentation for directives into one easy-to-reference guide, starting
with the former 'toctree' document. There are no changes to the content.
Signed-off-by: Stephen Finucane <stephen@that.guru>
These are very poorly documented at present, especially given their
power and use in basically all non-Napoleon based Python documentation.
Signed-off-by: Stephen Finucane <stephen@that.guru>
This is essentially the 'markup/inline' with a few small fixes. There
are also some modifications to the basic rST guide to highlight what a
role is; we were doing this for directives but not roles.
Signed-off-by: Stephen Finucane <stephen@that.guru>
This is taken from the existing 'rest' documents. Little to no
modifications are necessary, thankfully.
Signed-off-by: Stephen Finucane <stephen@that.guru>
This is simply the former 'tutorial' document renamed. A number of
references need to be updated, so this is done.
Signed-off-by: Stephen Finucane <stephen@that.guru>
Start structuring our docs a little better starting with a usage guide.
There are a number of changes happening here. We're going to start with
the installation guide, which is simply moved to the appropriate
subdirectory.
Signed-off-by: Stephen Finucane <stephen@that.guru>
