From d59f23b2c82dab1cf3d757584d117d15a6991284 Mon Sep 17 00:00:00 2001 From: Georg Brandl Date: Sun, 14 Feb 2016 09:37:55 +0100 Subject: [PATCH] Fix highlight languages in docs. --- doc/ext/napoleon.rst | 10 ++++++++-- doc/faq.rst | 2 +- doc/intl.rst | 28 ++++++++++++++++++---------- doc/invocation.rst | 16 +++++++++++----- 4 files changed, 38 insertions(+), 18 deletions(-) diff --git a/doc/ext/napoleon.rst b/doc/ext/napoleon.rst index 1531a3f27..304d8ac22 100644 --- a/doc/ext/napoleon.rst +++ b/doc/ext/napoleon.rst @@ -11,6 +11,8 @@ Napoleon - *Marching toward legible docstrings* =============================================== +.. highlight:: text + Are you tired of writing docstrings that look like this:: :param path: The path of the file to wrap @@ -124,7 +126,9 @@ Napoleon supports two styles of docstrings: `Google`_ and `NumPy`_. The main difference between the two styles is that Google uses indention to separate sections, whereas NumPy uses underlines. -Google style:: +Google style: + +.. code-block:: python3 def func(arg1, arg2): """Summary line. @@ -141,7 +145,9 @@ Google style:: """ return True -NumPy style:: +NumPy style: + +.. code-block:: python3 def func(arg1, arg2): """Summary line. diff --git a/doc/faq.rst b/doc/faq.rst index 313f1d034..04bd05717 100644 --- a/doc/faq.rst +++ b/doc/faq.rst @@ -213,7 +213,7 @@ If you want Emacs to display Info files produced by Sphinx using the value Info files, try adding the following Emacs Lisp code to your start-up file, ``~/.emacs.d/init.el``. -:: +.. code-block:: elisp (defadvice info-insert-file-contents (after sphinx-info-insert-file-contents diff --git a/doc/intl.rst b/doc/intl.rst index cbcc0a374..005b03601 100644 --- a/doc/intl.rst +++ b/doc/intl.rst @@ -88,14 +88,18 @@ This section describe a easy way to translate with sphinx-intl. :confval:`gettext_compact` is set to `False` (the Sphinx document is already configured as such). -#. Extract document's translatable messages into pot files:: +#. Extract document's translatable messages into pot files: + + .. code-block:: console $ make gettext As a result, many pot files are generated under ``_build/locale`` directory. -#. Setup/Update your `locale_dir`:: +#. Setup/Update your `locale_dir`: + + .. code-block:: console $ sphinx-intl update -p _build/locale -l de -l ja @@ -109,7 +113,9 @@ This section describe a easy way to translate with sphinx-intl. #. make translated document. You need a :confval:`language` parameter in ``conf.py`` or you may also - specify the parameter on the command line:: + specify the parameter on the command line: + + .. code-block:: console $ make -e SPHINXOPTS="-D language='de'" html @@ -163,7 +169,7 @@ and to apply differences to translated po files. In order to apply the updating difference of a pot file to po file, use the :command:`sphinx-intl update` command. -.. code-block:: bash +.. code-block:: console $ sphinx-intl update -p _build/locale @@ -182,7 +188,7 @@ easy to fetch and push translations. You need :command:`tx` command to upload resources (pot files). - .. code-block:: bash + .. code-block:: console $ pip install transifex-client @@ -206,7 +212,7 @@ easy to fetch and push translations. This process will create ``.tx/config`` in the current directory, as well as a ``~/.transifexrc`` file that includes auth information. - .. code-block:: bash + .. code-block:: console $ tx init Creating .tx folder... @@ -221,7 +227,7 @@ easy to fetch and push translations. Register pot files to ``.tx/config`` file: - .. code-block:: bash + .. code-block:: console $ cd /your/document/root $ sphinx-intl update-txconfig-resources --pot-dir _build/locale \ @@ -229,7 +235,7 @@ easy to fetch and push translations. and upload pot files: - .. code-block:: bash + .. code-block:: console $ tx push -s Pushing translations for resource sphinx-document-test_1_0.builders: @@ -248,7 +254,7 @@ easy to fetch and push translations. Get translated catalogs and build mo files (ex. for 'de'): - .. code-block:: bash + .. code-block:: console $ cd /your/document/root $ tx pull -l de @@ -257,7 +263,9 @@ easy to fetch and push translations. ... Done. - Invoke make html:: + Invoke make html: + + .. code-block:: console $ make -e SPHINXOPTS="-D language='de'" html diff --git a/doc/invocation.rst b/doc/invocation.rst index 8fe01bf8d..ce51fe080 100644 --- a/doc/invocation.rst +++ b/doc/invocation.rst @@ -6,7 +6,9 @@ Invocation of sphinx-quickstart =============================== The :program:`sphinx-quickstart` script generates a Sphinx documentation set. -It is called like this:: +It is called like this: + + .. code-block:: console $ sphinx-quickstart [options] [projectdir] @@ -141,9 +143,11 @@ Invocation of sphinx-build ========================== The :program:`sphinx-build` script builds a Sphinx documentation set. It is -called like this:: +called like this: - $ sphinx-build [options] sourcedir builddir [filenames] +.. code-block:: console + + $ sphinx-build [options] sourcedir builddir [filenames] where *sourcedir* is the :term:`source directory`, and *builddir* is the directory in which you want to place the built documentation. Most of the time, @@ -380,9 +384,11 @@ Invocation of sphinx-apidoc =========================== The :program:`sphinx-apidoc` generates completely automatic API documentation -for a Python package. It is called like this:: +for a Python package. It is called like this: - $ sphinx-apidoc [options] -o outputdir packagedir [pathnames] +.. code-block:: console + + $ sphinx-apidoc [options] -o outputdir packagedir [pathnames] where *packagedir* is the path to the package to document, and *outputdir* is the directory where the generated sources are placed. Any *pathnames* given