convert SGML guide to RST

[anarcat]

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

[anarcat]

result should look like this, more or less: http://anarcat-charybdis.readthedocs.io/en/rst-guide/

[anarcat]

i created a charybdis project on RTD to build those docs automatically in https://readthedocs.org/projects/charybdis/

however, it has trouble syncing webhooks here, which means it's not automatic just yet. this is probably because i don't have the right credentials, which was reported against rtd.org here: https://github.com/rtfd/readthedocs.org/issues/2746

i would be happy to grant developers here access to the docs project, let me know what your RTD username is and I'll add you.

[anarcat]

now the build is fixed:

http://charybdis.readthedocs.io/en/latest/