Opened 15 years ago

Closed 10 years ago

#148 closed task (fixed)

use ReST for documentation, not Lore

Reported by: Brian Warner Owned by: Brian Warner
Priority: major Milestone: 0.7.0
Component: documentation Version: 0.4.1
Keywords: review Cc:

Description (last modified by 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.

Change History (5)

comment:1 Changed 14 years ago by 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?

comment:2 Changed 14 years ago by Brian Warner

Milestone: 0.6.0eventually

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.

comment:3 Changed 13 years ago by Koblaid

Keywords: review added
Owner: set to Brian Warner

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:

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

comment:4 Changed 12 years ago by 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

comment:5 Changed 10 years ago by Brian Warner

Description: modified (diff)
Milestone: eventually0.7.0
Resolution: fixed
Status: newclosed

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!

Note: See TracTickets for help on using tickets.