diff options
Diffstat (limited to 'doc/faq.rst')
| -rw-r--r-- | doc/faq.rst | 354 |
1 files changed, 354 insertions, 0 deletions
diff --git a/doc/faq.rst b/doc/faq.rst new file mode 100644 index 0000000..85ccb24 --- /dev/null +++ b/doc/faq.rst @@ -0,0 +1,354 @@ +.. _faq: + +Sphinx FAQ +========== + +This is a list of Frequently Asked Questions about Sphinx. Feel free to +suggest new entries! + +How do I... +----------- + +... create PDF files without LaTeX? + `rinohtype`_ provides a PDF builder that can be used as a drop-in + replacement for the LaTeX builder. + + .. _rinohtype: https://github.com/brechtm/rinohtype + +... get section numbers? + They are automatic in LaTeX output; for HTML, give a ``:numbered:`` option to + the :rst:dir:`toctree` directive where you want to start numbering. + +... customize the look of the built HTML files? + Use themes, see :doc:`/usage/theming`. + +... add global substitutions or includes? + Add them in the :confval:`rst_prolog` or :confval:`rst_epilog` config value. + +... display the whole TOC tree in the sidebar? + Use the :data:`toctree` callable in a custom layout template, probably in the + ``sidebartoc`` block. + +... write my own extension? + See the :doc:`/development/tutorials/index`. + +... convert from my existing docs using MoinMoin markup? + The easiest way is to convert to xhtml, then convert `xhtml to reST`_. + You'll still need to mark up classes and such, but the headings and code + examples come through cleanly. + +For many more extensions and other contributed stuff, see the sphinx-contrib_ +repository. + +.. _sphinx-contrib: https://github.com/sphinx-contrib/ + +.. _usingwith: + +Using Sphinx with... +-------------------- + +Read the Docs + `Read the Docs <https://readthedocs.org>`_ is a documentation hosting + service based around Sphinx. They will host sphinx documentation, along + with supporting a number of other features including version support, PDF + generation, and more. The `Getting Started`_ guide is a good place to start. + +Epydoc + There's a third-party extension providing an `api role`_ which refers to + Epydoc's API docs for a given identifier. + +Doxygen + Michael Jones is developing a reST/Sphinx bridge to doxygen called `breathe + <https://github.com/michaeljones/breathe/tree/master>`_. + +SCons + Glenn Hutchings has written a SCons build script to build Sphinx + documentation; it is hosted here: + https://bitbucket-archive.softwareheritage.org/projects/zo/zondo/sphinx-scons.html + +PyPI + Jannis Leidel wrote a `setuptools command + <https://pypi.org/project/Sphinx-PyPI-upload/>`_ that automatically + uploads Sphinx documentation to the PyPI package documentation area at + https://pythonhosted.org/. + +GitHub Pages + Please add :py:mod:`sphinx.ext.githubpages` to your project. It allows you + to publish your document in GitHub Pages. It generates helper files for + GitHub Pages on building HTML document automatically. + +MediaWiki + See `sphinx-wiki`_, a project by Kevin Dunn. + + .. _sphinx-wiki: https://bitbucket-archive.softwareheritage.org/projects/ke/kevindunn/sphinx-wiki.html + +Google Analytics + You can use a custom ``layout.html`` template, like this: + + .. code-block:: html+jinja + + {% extends "!layout.html" %} + + {%- block extrahead %} + {{ super() }} + <script> + var _gaq = _gaq || []; + _gaq.push(['_setAccount', 'XXX account number XXX']); + _gaq.push(['_trackPageview']); + </script> + {% endblock %} + + {% block footer %} + {{ super() }} + <div class="footer">This page uses <a href="https://analytics.google.com/"> + Google Analytics</a> to collect statistics. You can disable it by blocking + the JavaScript coming from www.google-analytics.com. + <script> + (function() { + var ga = document.createElement('script'); + ga.src = ('https:' == document.location.protocol ? + 'https://ssl' : 'http://www') + '.google-analytics.com/ga.js'; + ga.setAttribute('async', 'true'); + document.documentElement.firstChild.appendChild(ga); + })(); + </script> + </div> + {% endblock %} + + +Google Search + To replace Sphinx's built-in search function with Google Search, proceed as + follows: + + 1. Go to https://cse.google.com/cse/all to create the Google Search code + snippet. + + 2. Copy the code snippet and paste it into ``_templates/searchbox.html`` in + your Sphinx project: + + .. code-block:: html+jinja + + <div> + <h3>{{ _('Quick search') }}</h3> + <script> + (function() { + var cx = '......'; + var gcse = document.createElement('script'); + gcse.async = true; + gcse.src = 'https://cse.google.com/cse.js?cx=' + cx; + var s = document.getElementsByTagName('script')[0]; + s.parentNode.insertBefore(gcse, s); + })(); + </script> + <gcse:search></gcse:search> + </div> + + 3. Add ``searchbox.html`` to the :confval:`html_sidebars` configuration value. + +.. _Getting Started: https://docs.readthedocs.io/en/stable/intro/getting-started-with-sphinx.html +.. _api role: https://git.savannah.gnu.org/cgit/kenozooid.git/tree/doc/extapi.py +.. _xhtml to reST: https://docutils.sourceforge.io/sandbox/xhtml2rest/xhtml2rest.py + + +Sphinx vs. Docutils +------------------- + +tl;dr: *docutils* converts reStructuredText to multiple output formats. Sphinx +builds upon docutils to allow construction of cross-referenced and indexed +bodies of documentation. + +`docutils`__ is a text processing system for converting plain text +documentation into other, richer formats. As noted in the `docutils +documentation`__, docutils uses *readers* to read a document, *parsers* for +parsing plain text formats into an internal tree representation made up of +different types of *nodes*, and *writers* to output this tree in various +document formats. docutils provides parsers for one plain text format - +`reStructuredText`__ - though other, *out-of-tree* parsers have been +implemented including Sphinx's :doc:`Markdown parser </usage/markdown>`. On the +other hand, it provides writers for many different formats including HTML, +LaTeX, man pages, Open Document Format and XML. + +docutils exposes all of its functionality through a variety of `front-end +tools`__, such as ``rst2html``, ``rst2odt`` and ``rst2xml``. Crucially though, +all of these tools, and docutils itself, are concerned with individual +documents. They don't support concepts such as cross-referencing, indexing of +documents, or the construction of a document hierarchy (typically manifesting +in a table of contents). + +Sphinx builds upon docutils by harnessing docutils' readers and parsers and +providing its own :doc:`/usage/builders/index`. As a result, Sphinx wraps some +of the *writers* provided by docutils. This allows Sphinx to provide many +features that would simply not be possible with docutils, such as those +outlined above. + +__ https://docutils.sourceforge.io/ +__ https://docutils.sourceforge.io/docs/dev/hacking.html +__ https://docutils.sourceforge.io/rst.html +__ https://docutils.sourceforge.io/docs/user/tools.html + + +.. _epub-faq: + +Epub info +--------- + +The following list gives some hints for the creation of epub files: + +* Split the text into several files. The longer the individual HTML files are, + the longer it takes the ebook reader to render them. In extreme cases, the + rendering can take up to one minute. + +* Try to minimize the markup. This also pays in rendering time. + +* For some readers you can use embedded or external fonts using the CSS + ``@font-face`` directive. This is *extremely* useful for code listings which + 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 <https://fontforge.github.io/>`_ and create + narrow variants of some free font. In my case I get up to 70 characters on a + line. + + You may have to experiment a little until you get reasonable results. + +* 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 + https://code.google.com/archive/p/threepress and run your own local server. + +* Large floating divs are not displayed properly. + If they cover more than one page, the div is only shown on the first page. + In that case you can copy the :file:`epub.css` from the + ``sphinx/themes/epub/static/`` directory to your local ``_static/`` + directory and remove the float settings. + +* Files that are inserted outside of the ``toctree`` directive must be manually + included. This sometimes applies to appendixes, e.g. the glossary or + the indices. You can add them with the :confval:`epub_post_files` option. + +* The handling of the epub cover page differs from the reStructuredText + procedure which automatically resolves image paths and puts the images + into the ``_images`` directory. For the epub cover page put the image in the + :confval:`html_static_path` directory and reference it with its full path in + the :confval:`epub_cover` config option. + +* kindlegen_ command can convert from epub3 resulting file to ``.mobi`` file + for Kindle. You can get ``yourdoc.mobi`` under ``_build/epub`` after the + following command: + + .. code-block:: bash + + $ make epub + $ kindlegen _build/epub/yourdoc.epub + + The kindlegen command doesn't accept documents that have section + titles surrounding ``toctree`` directive: + + .. code-block:: rst + + Section Title + ============= + + .. toctree:: + + subdocument + + Section After Toc Tree + ====================== + + kindlegen assumes all documents order in line, but the resulting document + has complicated order for kindlegen:: + + ``parent.xhtml`` -> ``child.xhtml`` -> ``parent.xhtml`` + + If you get the following error, fix your document structure: + + .. code-block:: none + + 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: https://calibre-ebook.com/ +.. _FBreader: https://fbreader.org/ +.. _Bookworm: https://www.oreilly.com/bookworm/index.html +.. _kindlegen: https://www.amazon.com/gp/feature.html?docId=1000765211 + +.. _texinfo-faq: + +Texinfo info +------------ + +There are two main programs for reading Info files, ``info`` and GNU Emacs. The +``info`` program has less features but is available in most Unix environments +and can be quickly accessed from the terminal. Emacs provides better font and +color display and supports extensive customization (of course). + +.. _texinfo-links: + +Displaying Links +~~~~~~~~~~~~~~~~ + +One noticeable problem you may encounter with the generated Info files is how +references are displayed. If you read the source of an Info file, a reference +to this section would look like:: + + * note Displaying Links: target-id + +In the stand-alone reader, ``info``, references are displayed just as they +appear in the source. Emacs, on the other-hand, will by default replace +``*note:`` with ``see`` and hide the ``target-id``. For example: + + :ref:`texinfo-links` + +One can disable generation of the inline references in a document +with :confval:`texinfo_cross_references`. That makes +an info file more readable with stand-alone reader (``info``). + +The exact behavior of how Emacs displays references is dependent on the variable +``Info-hide-note-references``. If set to the value of ``hide``, Emacs will hide +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 do take this behavior +into account. + +If you want Emacs to display Info files produced by Sphinx using the value +``hide`` for ``Info-hide-note-references`` and the default value for all other +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 + activate) + "Hack to make `Info-hide-note-references' buffer-local and + automatically set to `hide' iff it can be determined that this file + was created from a Texinfo file generated by Docutils or Sphinx." + (set (make-local-variable 'Info-hide-note-references) + (default-value 'Info-hide-note-references)) + (save-excursion + (save-restriction + (widen) (goto-char (point-min)) + (when (re-search-forward + "^Generated by \\(Sphinx\\|Docutils\\)" + (save-excursion (search-forward "\x1f" nil t)) t) + (set (make-local-variable 'Info-hide-note-references) + 'hide))))) + + +Notes +~~~~~ + +The following notes may be helpful if you want to create Texinfo files: + +- Each section corresponds to a different ``node`` in the Info file. + +- Colons (``:``) cannot be properly escaped in menu entries and xrefs. + They will be replaced with semicolons (``;``). + +- Links to external Info files can be created using the somewhat official URI + scheme ``info``. For example:: + + info:Texinfo#makeinfo_options |