solanum/doc/oper-guide/index.rst

.. Charybdis operator guide documentation master file, created by
   sphinx-quickstart on Sat Mar 25 10:41:29 2017.
   You can adapt this file completely to your liking, but it should at least
   contain the root `toctree` directive.

Welcome to Charybdis operator guide's documentation!
====================================================

Contents:

.. toctree::
   :maxdepth: 2


Indices and tables
==================

* :ref:`genindex`
* :ref:`modindex`
* :ref:`search`
convert SGML guide to RST the rationale behind switching away from SGML/Docbook is the following: * SGML is hard to edit for humans * the output is not much prettier * the toolchain is not well supported and missing from the build * the build is not hooked into anywhere, no automation the reason why RST was chosen: * it allows for a strong structure like Docbook * the theme from Read The Docs is pretty * it also supports mobile devices * sphinx can easily output to PDF and ePUB formats * RST is plaintext that can be easily edited and diff'd * RST can be automatically built by ReadTheDocs and the toolchain is readily available * the output is also parsed by Github so documentation can be read straight from GH the reason why Markdown was not chosen: * the current strong structure would be hard to replicate * markdown is not standardized and output varies according to the implementation the docs were converted with Pandoc, using the following commands: mkdir oper-guide for source in sgml/oper-guide/.sgml; do pandoc --toc -s -f docbook -t rst $source -o oper-guide/$(basename $source .sgml).rst done cd oper-guide sphinx-quickstart git add .rst make.bat conf.py git add -f Makefile git rm -r ../sgml [merged from d4214e9445d9f9d0f0ede3e09a9f81deee9: doc/sgml/oper-guide/config.sgml] 2017-03-25 14:42:32 +00:00			`.. Charybdis operator guide documentation master file, created by`
			`sphinx-quickstart on Sat Mar 25 10:41:29 2017.`
			`You can adapt this file completely to your liking, but it should at least`
			contain the root `toctree` directive.

			`Welcome to Charybdis operator guide's documentation!`
			`====================================================`

			`Contents:`

			`.. toctree::`
			`:maxdepth: 2`



			`Indices and tables`
			`==================`

			* :ref:`genindex`
			* :ref:`modindex`
			* :ref:`search`