diff --git a/doc/builders.rst b/doc/builders.rst index d3f5ef217..190f62cb9 100644 --- a/doc/builders.rst +++ b/doc/builders.rst @@ -84,7 +84,7 @@ The builder's "name" must be given to the **-b** command-line option of .. autoattribute:: supported_image_types - .. _Qt help: http://doc.qt.io/qt-4.8/qthelp-framework.html + .. _Qt help: https://doc.qt.io/qt-4.8/qthelp-framework.html .. module:: sphinx.builders.applehelp .. class:: AppleHelpBuilder @@ -229,7 +229,7 @@ The builder's "name" must be given to the **-b** command-line option of Note that a direct PDF builder using ReportLab is available in `rst2pdf `_ version 0.12 or greater. You need to add ``'rst2pdf.pdfbuilder'`` to your :confval:`extensions` to enable it, its name is -``pdf``. Refer to the `rst2pdf manual `_ +``pdf``. Refer to the `rst2pdf manual `_ for details. .. module:: sphinx.builders.text @@ -275,7 +275,7 @@ for details. the terminal-based program :program:`info`. See :ref:`texinfo-faq` for more details. The Texinfo format is the official documentation system used by the GNU project. More information on Texinfo can be found at - ``_. + ``_. .. autoattribute:: name diff --git a/doc/config.rst b/doc/config.rst index 407547fef..3aab2e7b2 100644 --- a/doc/config.rst +++ b/doc/config.rst @@ -764,7 +764,7 @@ that use Sphinx's HTMLWriter class. .. confval:: html_use_smartypants - If true, `SmartyPants `_ + If true, `SmartyPants `_ will be used to convert quotes and dashes to typographically correct entities. Default: ``True``. diff --git a/doc/develop.rst b/doc/develop.rst index 2f14c945f..4fc7792f7 100644 --- a/doc/develop.rst +++ b/doc/develop.rst @@ -27,19 +27,27 @@ releases on PyPI, others you can install from a checkout. This is the current list of contributed extensions in that repository: -- aafig: render embedded ASCII art as nice images using aafigure_. +- aafig: render embedded ASCII art as nice images using aafigure_ - actdiag: embed activity diagrams by using actdiag_ - adadomain: an extension for Ada support (Sphinx 1.0 needed) - ansi: parse ANSI color sequences inside documents -- autorun: Execute code in a ``runblock`` directive. +- argdoc: automatically generate documentation for command-line arguments, descriptions, and help text +- astah: embed diagram by using astah +- autoanysrc: Gather reST documentation from any source files +- autorun: Execute code in a ``runblock`` directive - blockdiag: embed block diagrams by using blockdiag_ +- cacoo: embed diagram from Cacoo +- cf3domain: a domain for CFEngine 3 policies +- cheader: The missing c:header directive for Sphinx's built-in C domain - cheeseshop: easily link to PyPI packages -- clearquest: create tables from ClearQuest_ queries. +- clearquest: create tables from ClearQuest_ queries - cmakedomain_: a domain for CMake_ -- coffeedomain: a domain for (auto)documenting CoffeeScript source code. -- context: a builder for ConTeXt. +- coffeedomain: a domain for (auto)documenting CoffeeScript source code +- context: a builder for ConTeXt +- disqus: embed Disqus comments in documents +- documentedlist: converts a Python list to a table in the generated documentation - doxylink: Link to external Doxygen-generated HTML documentation -- domaintools_: A tool for easy domain creation. +- domaintools_: A tool for easy domain creation - email: obfuscate email addresses - erlangdomain: an extension for Erlang support (Sphinx 1.0 needed) - exceltable: embed Excel spreadsheets into documents using exceltable_ @@ -47,47 +55,49 @@ This is the current list of contributed extensions in that repository: from your site content - findanything_: an extension to add Sublime Text 2-like findanything panels to your documentation to find pages, sections and index entries while typing -- gnuplot: produces images using gnuplot_ language. +- gnuplot: produces images using gnuplot_ language - googleanalytics: track web visitor statistics by using `Google Analytics`_ - googlechart: embed charts by using `Google Chart`_ - googlemaps: embed maps by using `Google Maps`_ -- httpdomain: a domain for documenting RESTful HTTP APIs. +- httpdomain: a domain for documenting RESTful HTTP APIs - hyphenator: client-side hyphenation of HTML using hyphenator_ +- imgur: embed Imgur images, albums, and metadata in documents - inlinesyntaxhighlight_: inline syntax highlighting - lassodomain: a domain for documenting Lasso_ source code -- libreoffice: an extension to include any drawing supported by LibreOffice (e.g. odg, vsd, ...). -- lilypond: an extension inserting music scripts from Lilypond_ in PNG format. +- libreoffice: an extension to include any drawing supported by LibreOffice (e.g. odg, vsd, ...) +- lilypond: an extension inserting music scripts from Lilypond_ in PNG format - makedomain_: a domain for `GNU Make`_ -- matlabdomain: document MATLAB_ code. -- mockautodoc: mock imports. -- mscgen: embed mscgen-formatted MSC (Message Sequence Chart)s. -- napoleon: supports `Google style`_ and `NumPy style`_ docstrings. +- matlabdomain: document MATLAB_ code +- mockautodoc: mock imports +- mscgen: embed mscgen-formatted MSC (Message Sequence Chart)s +- napoleon: supports `Google style`_ and `NumPy style`_ docstrings - nicovideo: embed videos from nicovideo - nwdiag: embed network diagrams by using nwdiag_ - omegat: support tools to collaborate with OmegaT_ (Sphinx 1.1 needed) - osaka: convert standard Japanese doc to Osaka dialect (this is a joke extension) -- paverutils: an alternate integration of Sphinx with Paver_. +- paverutils: an alternate integration of Sphinx with Paver_ - phpdomain: an extension for PHP support - plantuml: embed UML diagram by using PlantUML_ - py_directive: Execute python code in a ``py`` directive and return a math - node. -- rawfiles: copy raw files, like a CNAME. + node +- rawfiles: copy raw files, like a CNAME - requirements: declare requirements wherever you need (e.g. in test docstrings), mark statuses and collect them in a single list -- restbuilder: a builder for reST (reStructuredText) files. +- restbuilder: a builder for reST (reStructuredText) files - rubydomain: an extension for Ruby support (Sphinx 1.0 needed) - sadisplay: display SqlAlchemy model sadisplay_ - sdedit: an extension inserting sequence diagram by using Quick Sequence Diagram Editor (sdedit_) - seqdiag: embed sequence diagrams by using seqdiag_ -- slide: embed presentation slides on slideshare_ and other sites. +- slide: embed presentation slides on slideshare_ and other sites - swf_: embed flash files -- sword: an extension inserting Bible verses from Sword_. -- tikz: draw pictures with the `TikZ/PGF LaTeX package`_. +- sword: an extension inserting Bible verses from Sword_ +- tikz: draw pictures with the `TikZ/PGF LaTeX package`_ - traclinks: create TracLinks_ to a Trac_ instance from within Sphinx +- versioning: Sphinx extension that allows building versioned docs for self-hosting - whooshindex: whoosh indexer extension - youtube: embed videos from YouTube_ -- zopeext: provide an ``autointerface`` directive for using `Zope interfaces`_. +- zopeext: provide an ``autointerface`` directive for using `Zope interfaces`_ See the :ref:`extension tutorial ` on getting started with writing your diff --git a/doc/domains.rst b/doc/domains.rst index 9b2743645..838f40870 100644 --- a/doc/domains.rst +++ b/doc/domains.rst @@ -34,8 +34,8 @@ documentation wants to refer to e.g. C++ and Python classes. It also means that extensions that support the documentation of whole new languages are much easier to write. -This section describes what the domains that come with Sphinx provide. The -domain API is documented as well, in the section :ref:`domain-api`. +This section describes what the domains that are included with Sphinx provide. +The domain API is documented as well, in the section :ref:`domain-api`. .. _basic-domain-markup: diff --git a/doc/extensions.rst b/doc/extensions.rst index afd211c34..c005218e8 100644 --- a/doc/extensions.rst +++ b/doc/extensions.rst @@ -4,7 +4,7 @@ Sphinx Extensions ================= Since many projects will need special features in their documentation, Sphinx -allows to add "extensions" to the build process, each of which can modify almost +allows adding "extensions" to the build process, each of which can modify almost any aspect of document processing. This chapter describes the extensions bundled with Sphinx. For the API diff --git a/doc/faq.rst b/doc/faq.rst index 5924f5f68..133614ef2 100644 --- a/doc/faq.rst +++ b/doc/faq.rst @@ -140,7 +140,7 @@ The following list gives some hints for the creation of epub files: are often cut at the right margin. The default Courier font (or variant) is quite wide and you can only display up to 60 characters on a line. If you replace it with a narrower font, you can get more characters on a line. You - may even use `FontForge `_ and create + may even use `FontForge `_ and create narrow variants of some free font. In my case I get up to 70 characters on a line. @@ -148,7 +148,7 @@ The following list gives some hints for the creation of epub files: * Test the created epubs. You can use several alternatives. The ones I am aware of are Epubcheck_, Calibre_, FBreader_ (although it does not render the CSS), - and Bookworm_. For bookworm you can download the source from + and Bookworm_. For Bookworm, you can download the source from https://code.google.com/archive/p/threepress and run your own local server. * Large floating divs are not displayed properly. @@ -176,7 +176,7 @@ The following list gives some hints for the creation of epub files: $ make epub $ kindlegen _build/epub/yourdoc.epub - kindlegen commands doesn't accept documents that have section + The kindlegen command doesn't accept documents that have section titles surrounding ``toctree`` directive: .. code-block:: rst @@ -191,18 +191,18 @@ The following list gives some hints for the creation of epub files: Section After Toc Tree ====================== - kindlegen assumes all documents order in line, but resulting document - has complecated order for kindlegen:: + kindlegen assumes all documents order in line, but the resulting document + has complicated order for kindlegen:: ``parent.xhtml`` -> ``child.xhtml`` -> ``parent.xhtml`` - If you got the following error, fix document structure:: + If you get the following error, fix your document structure:: Error(prcgen):E24011: TOC section scope is not included in the parent chapter:(title) Error(prcgen):E24001: The table of content could not be built. .. _Epubcheck: https://github.com/IDPF/epubcheck -.. _Calibre: http://calibre-ebook.com/ +.. _Calibre: https://calibre-ebook.com/ .. _FBreader: https://fbreader.org/ .. _Bookworm: http://www.oreilly.com/bookworm/index.html .. _kindlegen: https://www.amazon.com/gp/feature.html?docId=1000765211 @@ -239,7 +239,7 @@ The exact behavior of how Emacs displays references is dependent on the variable both the ``*note:`` part and the ``target-id``. This is generally the best way to view Sphinx-based documents since they often make frequent use of links and do not take this limitation into account. However, changing this variable -affects how all Info documents are displayed and most due take this behavior +affects how all Info documents are displayed and most do take this behavior into account. If you want Emacs to display Info files produced by Sphinx using the value diff --git a/doc/latex.rst b/doc/latex.rst index 7a408afd1..2f68899f8 100644 --- a/doc/latex.rst +++ b/doc/latex.rst @@ -57,7 +57,7 @@ in Python string literals to reach latex.) For example:: } latex_show_urls = 'footnote' -.. the above was tested on Sphinx's own 1.5a2 documentation with good effect ! +.. the above was tested on Sphinx's own 1.5a2 documentation with good effect! .. highlight:: latex @@ -92,8 +92,8 @@ string of ``key=value`` instructions:: key1=value1,key2=value2, ... -- if a key is repeated, it is its last occurence which counts, -- spaces around the commas and equal signs are ignored. +- if a key is repeated, it is its last occurence which is used +- spaces around the commas and equal signs are ignored If non-empty, it will be passed as argument to the ``\sphinxsetup`` command:: @@ -148,7 +148,7 @@ Here are the currently available options together with their default values. .. attention:: - LaTeX requires for keys with Boolean values to use **lowercase** ``true`` or + LaTeX requires that keys with Boolean values use **lowercase** ``true`` or ``false``. .. _latexsphinxsetuphmargin: @@ -215,8 +215,8 @@ Here are the currently available options together with their default values. .. (comment) It is theoretically possible to customize this even more and decide at which characters a line-break can occur and whether - before or after, but this is accessible currently only by re-defining some - macros with complicated LaTeX syntax from :file:`sphinx.sty`. + before or after, but this is accessible currently only by re-defining + some macros with complicated LaTeX syntax from :file:`sphinx.sty`. ``parsedliteralwraps`` default ``true``. Tells whether long lines in :dudir:`parsed-literal`\ 's @@ -230,8 +230,7 @@ Here are the currently available options together with their default values. potential break-points (additionally to those allowed by LaTeX at spaces or for hyphenation) are currently inserted only after the characters ``. , ; ? ! /``. Due to TeX internals, white space in the line will be - stretched - (or shrinked) in order to accomodate the linebreak. + stretched (or shrunk) in order to accomodate the linebreak. .. versionadded:: 1.5 set this option value to ``false`` to recover former behaviour. diff --git a/doc/setuptools.rst b/doc/setuptools.rst index a8666a0bd..dab25fc59 100644 --- a/doc/setuptools.rst +++ b/doc/setuptools.rst @@ -10,7 +10,7 @@ Using setuptools integration ---------------------------- The Sphinx build can then be triggered from distutils, and some Sphinx -options can be set in ``setup.py`` or ``setup.cfg`` instead of Sphinx own +options can be set in ``setup.py`` or ``setup.cfg`` instead of Sphinx's own configuration file. For instance, from ``setup.py``::