IntenseWebs/sphinx
3
0
Fork 0
mirror of https://github.com/sphinx-doc/sphinx.git synced 2025-02-25 18:55:22 -06:00
Code Issues Packages Projects Releases Wiki Activity

docs: Compare docutils with Sphinx

Browse Source 
Add an FAQ entry comparing the two.

Signed-off-by: Stephen Finucane <stephen@that.guru>
This commit is contained in:
Stephen Finucane 2017-04-03 10:09:11 +01:00
parent 9988d5ce26
commit aaf2dafd63
1 changed files with 37 additions and 0 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

37
doc/faq.rst
View File

@ -148,6 +148,43 @@ Google Search
.. _xhtml to reST: http://docutils.sourceforge.net/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.
__ http://docutils.sourceforge.io/
__ http://docutils.sourceforge.io/docs/dev/hacking.html
__ http://docutils.sourceforge.io/rst.html
__ http://docutils.sourceforge.net/docs/user/tools.html
.. _epub-faq:
Epub info