use ReST for documentation, not Lore

[Brian Warner]

The Twisted gang tells me that Lore is going away, and that I should rewrite the docs in Restructured Text instead. Sounds reasonable.

[koblaid]

Is this ticket still active? I would try to do some of the docs, although I dont know if I can make all of them. I would beginn with using-foolscap.xhtml.

Are there any special requirements for ReST?

[Brian Warner]

yup, it's still active. Thanks for the offer! I don't think there are any special requirements.. just look at what Twisted did and do something similar.

[Koblaid]

Hi,

I made some progress in the conversion from sphinx to lore.

What I've done:

• got lore2sphinx and sphinx running (lore2sphinx needed some bufixes)
• added commands for lore2sphinx and sphinx to the Makefile
• added folders doc_rst and doc_html
• added a dummy index.rst

To build the docs you need:

• lore2sphinx: ​https://bitbucket.org/khorn/lore2sphinx/overview
• Sphinx
• foolscap branch: ​https://github.com/Koblaid/foolscap/tree/sphinx-doc

Build the docs:

1. run "make lore2rest" (this doesn't work at the moment, so I commited the converted rst files to the branch)
2. run "make html"
3. open doc_html/html/index.html in a browser

Todo: The html output looks nice, but there are still some errors in the rst files. Sphinx complains over syntax errors and there are some minor errors in the html output.

These errors should be fixed in the rst files. It would be good to have a review of the output of lore2sphinx before fixing the rst files manually. This way lore2sphinx could be changed and run again without losing the manual fixes.

Once the lore2sphinx conversion is ok, I'll start fixing the rst files.

Greetings Koblaid

[Koblaid]

Are you still interested in converting the docs to sphinx? I have free time at the moment so I could continue to work at it

[Brian Warner]

I finally landed some of this, in [b0e2718a01], using .rst files as the primary sources (instead of sphinx) so that github will render it nicely. I think that's probably good enough. Thanks so much!