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 )
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
comment:2 Changed 14 years ago by
Milestone: | 0.6.0 → eventually |
---|
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
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:
- lore2sphinx: https://bitbucket.org/khorn/lore2sphinx/overview
- Sphinx
- foolscap branch: https://github.com/Koblaid/foolscap/tree/sphinx-doc
Build the docs:
- run "make lore2rest" (this doesn't work at the moment, so I commited the converted rst files to the branch)
- run "make html"
- 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
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
Description: | modified (diff) |
---|---|
Milestone: | eventually → 0.7.0 |
Resolution: | → fixed |
Status: | new → closed |
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!
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?