vulpineawoo/solanum
1
0
Fork 0
Code Issues Pull requests Projects Releases Wiki Activity
solanum/doc/oper-guide/index.rst

30 lines
579 B
ReStructuredText
Raw Normal View History

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.
merge two index pages
2017-03-25 15:09:44 +00:00
============================================
Operators guide for the charybdis IRC server
============================================
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
Contents:
.. toctree::
fix duplicate headings, remove duplicate ToC
2017-03-25 15:15:03 +00:00
:maxdepth: 1
merge two index pages
2017-03-25 15:09:44 +00:00
intro
umodes
cmodes
ucommands
commands
oprivs
config
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
Indices and tables
==================
* :ref:`genindex`
* :ref:`modindex`
* :ref:`search`
Reference in a new issue Copy permalink