Merge pull request #3843 from ghane/PROOF

Proofreading: Typos, and one updation of list

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
 <https://github.com/rst2pdf/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 <http://ralsina.me/static/manual.pdf>`_
+``pdf``.  Refer to the `rst2pdf manual <https://ralsina.me/static/manual.pdf>`_
 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
-   `<http://www.gnu.org/software/texinfo/>`_.
+   `<https://www.gnu.org/software/texinfo/>`_.
 
    .. autoattribute:: name
 

doc/config.rst

@@ -764,7 +764,7 @@ that use Sphinx's HTMLWriter class.
 
 .. confval:: html_use_smartypants
 
-   If true, `SmartyPants <http://daringfireball.net/projects/smartypants/>`_
+   If true, `SmartyPants <https://daringfireball.net/projects/smartypants/>`_
    will be used to convert quotes and dashes to typographically correct
    entities.  Default: ``True``.
 

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.
+- coffeedomain: a domain for (auto)documenting CoffeeScript source code
-- context: a builder for ConTeXt.
+- 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, ...).
+- 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.
+- lilypond: an extension inserting music scripts from Lilypond_ in PNG format
 - makedomain_: a domain for `GNU Make`_
-- matlabdomain: document MATLAB_ code.
+- matlabdomain: document MATLAB_ code
-- mockautodoc: mock imports.
+- mockautodoc: mock imports
-- mscgen: embed mscgen-formatted MSC (Message Sequence Chart)s.
+- mscgen: embed mscgen-formatted MSC (Message Sequence Chart)s
-- napoleon: supports `Google style`_ and `NumPy style`_ docstrings.
+- 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.
+  node
-- rawfiles: copy raw files, like a CNAME.
+- 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_.
+- sword: an extension inserting Bible verses from Sword_
-- tikz: draw pictures with the `TikZ/PGF LaTeX package`_.
+- 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 <exttut>` on getting started with writing your

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
+This section describes what the domains that are included with Sphinx provide.
-domain API is documented as well, in the section :ref:`domain-api`.
+The domain API is documented as well, in the section :ref:`domain-api`.
 
 
 .. _basic-domain-markup:

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

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 <http://fontforge.github.io/>`_ and create
+  may even use `FontForge <https://fontforge.github.io/>`_ 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
+  kindlegen assumes all documents order in line, but the resulting document
-  has complecated order for kindlegen::
+  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

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,
+- if a key is repeated, it is its last occurence which is used
-- spaces around the commas and equal signs are ignored.
+- 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
+       before or after, but this is accessible currently only by re-defining
-       macros with complicated LaTeX syntax from :file:`sphinx.sty`.
+       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
+    stretched (or shrunk) in order to accomodate the linebreak.
-    (or shrinked) in order to accomodate the linebreak.
 
     .. versionadded:: 1.5
        set this option value to ``false`` to recover former behaviour.

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``::