#27 Documentation in reST?

closed
nobody
None
9
2005-02-14
2005-02-08
No

I thought it may be good to theve the documentation
written in ducutls reST format. So many output formats
like HTML could be used. Maybe I could help a bit with
conversion.

Again: small functional value, but nice to have :)

Discussion

  • Daniel Pozmanter

    Logged In: YES
    user_id=796750

    I am not particularly familiar with reST. If you wanted to
    try converting some docs, and it looks nicer, then sure thing.

    What are the advantages?

     
  • Daniel Pozmanter

    • priority: 5 --> 3
     
  • Marek Kubica

    Marek Kubica - 2005-02-09

    Logged In: YES
    user_id=872713

    Pure reST files (with all that markup) are still human
    readable, even with pagers like less.
    The advantages are that there are many output formats, so
    converting to HTML is no problem, LaTeX is also supported,
    and writers for DocBook, Manpage and PDF are started.
    Docutils is free, written in Python and authored by many
    Python developers.

    You could tell me which documents are not changed very
    often, so I could try to convert then to reST and see
    wherter that is a good idea.

     
  • Daniel Pozmanter

    • status: open --> closed
     
  • Daniel Pozmanter

    Logged In: YES
    user_id=796750

    Hmnnn. Well, I *would* have said gpl.html, but I just
    changed it.
    I'd suggest starting with help.html.

    If that looks nice, post it as a Patch, and if it looks
    good, then we can use that.

    The advnatage of producing other formats would be neat,
    although, do we *need* other formats (well for this project
    anyway)?

    At the moment, the docs are easy to edit, and they've just
    been reworked with css to make them look rather nice (Plus,
    I can just edit the css to changed the formatting for all of
    them).

    The only advantage I see is being able to read them with a
    text editor, which does not seem like enough.

    So for the moment I am going to close this tracker, but if
    you can come up with an example page, add a post in the
    forum, and we will put it up for a vote/discussion.

     
  • Marek Kubica

    Marek Kubica - 2005-02-11

    Logged In: YES
    user_id=872713

    I found a page written using reST:
    http://colorstudy.com/docs/python/shootout.html well, I try
    to make a page like this with docutils.

    I also found a tool to convert reST to CHM, so that's
    another output format.

    So, I'll try to convert help.html..

     
  • Marek Kubica

    Marek Kubica - 2005-02-11

    Logged In: YES
    user_id=872713

    I've attached a sample page (although the tracker is
    currently closed) and I'm going to post in the forum.

     
  • Daniel Pozmanter

    Logged In: YES
    user_id=796750

    WOW!

    This looks REALLY nice.

    Yes, if you could do the docs in this, it would be awesome.

    Really nice sense of aesthetic!

     
  • Daniel Pozmanter

    • priority: 3 --> 9
    • status: closed --> open
     
  • Marek Kubica

    Marek Kubica - 2005-02-12

    Logged In: YES
    user_id=872713

    I've attached a snapshot of the documentation, it is not yet
    ready, but I thought you may be interessted (as this RFE has
    such a high Priority :)
    Finished documents: dis, thanks, help, gpl.

    The txt files are the reST sources, the html files are
    created using rst2html.py from the docutils 0.3.7 tarball.
    I'll work on, it is fun to help to make DrPython better
    (even when it's just the documentation)

    I don't know, maybe it would be best to make all documents
    (except the GPL) one big file?

     
  • Daniel Pozmanter

    Logged In: YES
    user_id=796750

    Yes, this looks very good. If you can get the basic stuff
    done, I can update the docs accordingly (although if you use
    3.10.3 for the rest, that would be cool).

    As for the priority, :). This just looks much cleaner and
    clearer than what was there before. Plus, it will be much
    easier for me to mess with in the future.

    As for making all the docs one big file.... There will be
    some work on the docs in the future (throught the toronto
    project), so I am not inclined to do anything major to the
    docs themselves as of yet (although changing the format is
    fine).

     
  • Marek Kubica

    Marek Kubica - 2005-02-14

    Logged In: YES
    user_id=872713

    Okay, I'll reformat credits, plugins, and drscript from
    3.10.3, the rest is already done.

     
  • Marek Kubica

    Marek Kubica - 2005-02-14

    The final docs in reST format + HTML

     
  • Marek Kubica

    Marek Kubica - 2005-02-14

    Logged In: YES
    user_id=872713

    Attached: the final docs in rest format, including pictures
    and generated HTML pages. Generated using docutils 0.3.7
    rst2html script. All changes should be made to the txt files
    and then converted to HTML.

    The docs should reflect Dr 3.10.3.

     
  • Daniel Pozmanter

    • status: open --> closed
     
  • Daniel Pozmanter

    Logged In: YES
    user_id=796750

    Many thanks.

    I made the necessary updates.

    This will be in 3.10.4.

    Any idea for displaying code? The syntax highlighting bit
    does not seem to exist here.

    If not, I can extend the wrapper I wrote to find source code,
    and replace it with formatted html.

    Of course, if something already exists to do this, that
    would be ideal.

    This is *much* easier to maintain! Thanks!

     
  • Marek Kubica

    Marek Kubica - 2005-02-15

    Logged In: YES
    user_id=872713

    Uhm, well, I found this:
    http://aspn.activestate.com/ASPN/Cookbook/Python/Recipe/252170/

    I don't know how good that is, but it seems to work and have
    support for many Scintilla highlighters. I don't see py24
    binaries for silvercity, but I can try to produce some.

     

Log in to post a comment.

Get latest updates about Open Source Projects, Conferences and News.

Sign up for the SourceForge newsletter:

JavaScript is required for this form.





No, thanks