[Chris asked me to bring this up on the mailing list some time ago, but I couldn't get to it. Sorry for that.] Since the beginning, I used ReST [1] for documenting llvmc, instead of plain HTML that was used historically. In my opinion, ReST is much easier to write and read (in the text editor or on terminal); it can also be used to produce PDFs, man pages or HTML that looks exactly the same as the rest of LLVM documentation (see [2] for example). However, there are benefits in having a standardized procedure. I propose that we allow using ReST (or some other lightweight markup language that the majority agrees upon) for new documentation on the grounds that this doesn't add too much overhead (generated HTML is already used for man pages, for example). Since it is better to use a single format for documentation, the rest of the docs should probably be also converted in the long term. [1] http://docutils.sourceforge.net/rst.html [2] http://llvm.org/docs/CompilerDriver.html (Note: this document is out of date; I've updated the style sheet since then.)
Just to add an extra note: There is a nice doc generator for Python that takes ReST docs and produces very nice HTML output. It is now used for the Python standard library, in addition to many packages. http://sphinx.pocoo.org/ For example, see: http://docs.python.org/dev/ Hit 'view source' on the side of some pages (particularly the non-reference pages) to see what ReST looks like. While Sphinx doesn't work for documenting C++ API's like doxygen, it is possible to use it as a way of making general docs via ReST. As an added bonus, it is very easy to add plugins to ReST and sphinx; for example, I imagine making a graphviz plugin to visualize CFG's or a pygments plugin for syntax highlighting LLVM intermediate code would be useful. Keir On Tue, Dec 9, 2008 at 7:56 AM, Mikhail Glushenkov <foldr at codedgers.com>wrote:> [Chris asked me to bring this up on the mailing list some time > ago, but I couldn't get to it. Sorry for that.] > > Since the beginning, I used ReST [1] for documenting llvmc, instead of > plain HTML that was used historically. In my opinion, ReST is much > easier to write and read (in the text editor or on terminal); it can > also be used to produce PDFs, man pages or HTML that looks exactly the > same as the rest of LLVM documentation (see [2] for example). However, > there are benefits in having a standardized procedure. > > I propose that we allow using ReST (or some other lightweight markup > language that the majority agrees upon) for new documentation on the > grounds that this doesn't add too much overhead (generated HTML is > already used for man pages, for example). > > Since it is better to use a single format for documentation, the rest > of the docs should probably be also converted in the long term. > > > > [1] http://docutils.sourceforge.net/rst.html > > [2] http://llvm.org/docs/CompilerDriver.html > (Note: this document is out of date; I've updated the style sheet since > then.) > > > _______________________________________________ > LLVM Developers mailing list > LLVMdev at cs.uiuc.edu http://llvm.cs.uiuc.edu > http://lists.cs.uiuc.edu/mailman/listinfo/llvmdev >-------------- next part -------------- An HTML attachment was scrubbed... URL: <http://lists.llvm.org/pipermail/llvm-dev/attachments/20081209/78d77991/attachment.html>
Can you compare ReST to docbook? We've talked about using docbook for a long time. What are the pros and cons of each? Thanks, Tanya On Dec 9, 2008, at 7:56 AM, Mikhail Glushenkov wrote:> [Chris asked me to bring this up on the mailing list some time > ago, but I couldn't get to it. Sorry for that.] > > Since the beginning, I used ReST [1] for documenting llvmc, instead of > plain HTML that was used historically. In my opinion, ReST is much > easier to write and read (in the text editor or on terminal); it can > also be used to produce PDFs, man pages or HTML that looks exactly the > same as the rest of LLVM documentation (see [2] for example). However, > there are benefits in having a standardized procedure. > > I propose that we allow using ReST (or some other lightweight markup > language that the majority agrees upon) for new documentation on the > grounds that this doesn't add too much overhead (generated HTML is > already used for man pages, for example). > > Since it is better to use a single format for documentation, the rest > of the docs should probably be also converted in the long term. > > > > [1] http://docutils.sourceforge.net/rst.html > > [2] http://llvm.org/docs/CompilerDriver.html > (Note: this document is out of date; I've updated the style sheet > since > then.) > > > _______________________________________________ > LLVM Developers mailing list > LLVMdev at cs.uiuc.edu http://llvm.cs.uiuc.edu > http://lists.cs.uiuc.edu/mailman/listinfo/llvmdev
WikiFormatting for code documentation? :-) -scooter On Tue, Dec 9, 2008 at 7:56 AM, Mikhail Glushenkov <foldr at codedgers.com>wrote:> [Chris asked me to bring this up on the mailing list some time > ago, but I couldn't get to it. Sorry for that.] > > Since the beginning, I used ReST [1] for documenting llvmc, instead of > plain HTML that was used historically. In my opinion, ReST is much > easier to write and read (in the text editor or on terminal); it can > also be used to produce PDFs, man pages or HTML that looks exactly the > same as the rest of LLVM documentation (see [2] for example). However, > there are benefits in having a standardized procedure. > > I propose that we allow using ReST (or some other lightweight markup > language that the majority agrees upon) for new documentation on the > grounds that this doesn't add too much overhead (generated HTML is > already used for man pages, for example). > > Since it is better to use a single format for documentation, the rest > of the docs should probably be also converted in the long term. > > > > [1] http://docutils.sourceforge.net/rst.html > > [2] http://llvm.org/docs/CompilerDriver.html > (Note: this document is out of date; I've updated the style sheet since > then.) > > > _______________________________________________ > LLVM Developers mailing list > LLVMdev at cs.uiuc.edu http://llvm.cs.uiuc.edu > http://lists.cs.uiuc.edu/mailman/listinfo/llvmdev >-------------- next part -------------- An HTML attachment was scrubbed... URL: <http://lists.llvm.org/pipermail/llvm-dev/attachments/20081209/3b434602/attachment.html>
I have no docbook experience. However, there is a ReST to docbook converter available: http://docutils.sourceforge.net/sandbox/oliverr/docbook/ Keir On Tue, Dec 9, 2008 at 10:35 AM, Tanya Lattner <tonic at nondot.org> wrote:> Can you compare ReST to docbook? We've talked about using docbook for > a long time. What are the pros and cons of each? > > Thanks, > Tanya > > On Dec 9, 2008, at 7:56 AM, Mikhail Glushenkov wrote: > > > [Chris asked me to bring this up on the mailing list some time > > ago, but I couldn't get to it. Sorry for that.] > > > > Since the beginning, I used ReST [1] for documenting llvmc, instead of > > plain HTML that was used historically. In my opinion, ReST is much > > easier to write and read (in the text editor or on terminal); it can > > also be used to produce PDFs, man pages or HTML that looks exactly the > > same as the rest of LLVM documentation (see [2] for example). However, > > there are benefits in having a standardized procedure. > > > > I propose that we allow using ReST (or some other lightweight markup > > language that the majority agrees upon) for new documentation on the > > grounds that this doesn't add too much overhead (generated HTML is > > already used for man pages, for example). > > > > Since it is better to use a single format for documentation, the rest > > of the docs should probably be also converted in the long term. > > > > > > > > [1] http://docutils.sourceforge.net/rst.html > > > > [2] http://llvm.org/docs/CompilerDriver.html > > (Note: this document is out of date; I've updated the style sheet > > since > > then.) > > > > > > _______________________________________________ > > LLVM Developers mailing list > > LLVMdev at cs.uiuc.edu http://llvm.cs.uiuc.edu > > http://lists.cs.uiuc.edu/mailman/listinfo/llvmdev > > _______________________________________________ > LLVM Developers mailing list > LLVMdev at cs.uiuc.edu http://llvm.cs.uiuc.edu > http://lists.cs.uiuc.edu/mailman/listinfo/llvmdev >-------------- next part -------------- An HTML attachment was scrubbed... URL: <http://lists.llvm.org/pipermail/llvm-dev/attachments/20081209/12f3d9f8/attachment.html>
Another alternative with wikiformating producing docbook is Quickbook: http://www.boost.org/doc/libs/1_37_0/doc/html/quickbook.html However, I am not advocating this tools, I just wanted to mention it in the discution. The main advantage is good C++ integration but the doc build chain is long and don't work so well. I expect this to change as boost is moving most of its documentaiton to this format. Cédric Scott Michel a écrit :> WikiFormatting for code documentation? :-) > > > -scooter > > On Tue, Dec 9, 2008 at 7:56 AM, Mikhail Glushenkov > <foldr at codedgers.com <mailto:foldr at codedgers.com>> wrote: > > [Chris asked me to bring this up on the mailing list some time > ago, but I couldn't get to it. Sorry for that.] > > Since the beginning, I used ReST [1] for documenting llvmc, instead of > plain HTML that was used historically. In my opinion, ReST is much > easier to write and read (in the text editor or on terminal); it can > also be used to produce PDFs, man pages or HTML that looks exactly the > same as the rest of LLVM documentation (see [2] for example). However, > there are benefits in having a standardized procedure. > > I propose that we allow using ReST (or some other lightweight markup > language that the majority agrees upon) for new documentation on the > grounds that this doesn't add too much overhead (generated HTML is > already used for man pages, for example). > > Since it is better to use a single format for documentation, the rest > of the docs should probably be also converted in the long term. > > > > [1] http://docutils.sourceforge.net/rst.html > > [2] http://llvm.org/docs/CompilerDriver.html > (Note: this document is out of date; I've updated the style sheet > since > then.) > > > _______________________________________________ > LLVM Developers mailing list > LLVMdev at cs.uiuc.edu <mailto:LLVMdev at cs.uiuc.edu> > http://llvm.cs.uiuc.edu <http://llvm.cs.uiuc.edu/> > http://lists.cs.uiuc.edu/mailman/listinfo/llvmdev > > > ------------------------------------------------------------------------ > > _______________________________________________ > LLVM Developers mailing list > LLVMdev at cs.uiuc.edu http://llvm.cs.uiuc.edu > http://lists.cs.uiuc.edu/mailman/listinfo/llvmdev >
I've been using Sphinx, the tool Kier mentions, for my own documentation
needs. I've been using it for over six months and so I am fairly
familiar with it.
ReST is, as mentioned, is a markup language that is inspired by
WikiNotation, but more targeted at producing technical documentation
rather than informal collaborative editing of web pages. Sphinx extends
ReST in this direction even further, providing markup elements for
functions, classes, methods, statements, macros, and other programming
constructs -- essentially it defines a set of semantic markup
conventions which are represented in ReST syntax.
The major advantage of ReST over HTML or LaTeX is that the source
documentation is readable as text. The markup conventions are
lightweight and minimal, avoiding clutter, yet completely deterministic
and rigorous in meaning. Here's a sample taken from my own documentation:
The "with" statement
--------------------
Another useful statement is the :stmt:`with` statement::
// Declare a new variable 'fh' and assign an open file handle to it.
with fh = File.open("unicode.txt) {
// Do something with fh.
// It will be closed when the block exits.
}
The :stmt:`with` statement can be used to guarantee that the appropriate
cleanup code is called after you are finished with an object. In the above
example, the file handle ``fh`` will be closed upon exit from the
:stmt:`with` block, regardless of how the block was existed (even if via
:stmt:`return` or an exception.)
The :stmt:`with` statement can also influence the set of effect
annotations
that propagate outward from within the contained block. Similar to the
way a
:stmt:`try` statement can filter out an exception effect, a :stmt:`with`
statement that acquires and then releases a mutex could potentially
remove a 'thread-unsafe' effect.
The ":stmt:" modifier creates inline hyperlink to the documentation
for
the specified statement. It also generates an entry in the index under
"Statements".
The indented code example will be automatically syntax-colored. In this
case, its using a custom syntax definition for the language I am
writing, however there are syntax definitions available for several
dozen popular languages already. (It would be relatively easy, for
example, to create a syntax definition for LLVM IR.)
Sphinx was originally written to solve the problem of documentation in
Python. For many years, the Python reference manuals were written in
LaTeX. The problem with this is that it made it difficult to get
contributors to submit documentation patches. Few people know LaTeX
these days, and the tool chain for producing HTML from LaTeX sources is
complex and difficult to install and use.
Georg Brandl, the creator of Sphinx, wrote a LaTeX-to-ReST converter,
and converted all of Python's documentation to ReST. He also provide the
tools needed to convert and maintain the documentation. Since that time,
the number of outside contributions to the Python documentation has
increased dramatically. (I don't have exact stats, but I could probably
get them if needed.)
It was because of this experience with Python that I decided to give
Sphinx a try with my own docs. So far I have been quite pleased with the
results.
Here's the main Sphinx site:
http://sphinx.pocoo.org/
I highly recommend browsing some of the examples and looking at other
projects using Sphinx.
-- Talin
Tanya Lattner wrote:> Can you compare ReST to docbook? We've talked about using docbook for
> a long time. What are the pros and cons of each?
>
> Thanks,
> Tanya
>
> On Dec 9, 2008, at 7:56 AM, Mikhail Glushenkov wrote:
>
>
>> [Chris asked me to bring this up on the mailing list some time
>> ago, but I couldn't get to it. Sorry for that.]
>>
>> Since the beginning, I used ReST [1] for documenting llvmc, instead of
>> plain HTML that was used historically. In my opinion, ReST is much
>> easier to write and read (in the text editor or on terminal); it can
>> also be used to produce PDFs, man pages or HTML that looks exactly the
>> same as the rest of LLVM documentation (see [2] for example). However,
>> there are benefits in having a standardized procedure.
>>
>> I propose that we allow using ReST (or some other lightweight markup
>> language that the majority agrees upon) for new documentation on the
>> grounds that this doesn't add too much overhead (generated HTML is
>> already used for man pages, for example).
>>
>> Since it is better to use a single format for documentation, the rest
>> of the docs should probably be also converted in the long term.
>>
>>
>>
>> [1] http://docutils.sourceforge.net/rst.html
>>
>> [2] http://llvm.org/docs/CompilerDriver.html
>> (Note: this document is out of date; I've updated the style sheet
>> since
>> then.)
>>
>>
>> _______________________________________________
>> LLVM Developers mailing list
>> LLVMdev at cs.uiuc.edu http://llvm.cs.uiuc.edu
>> http://lists.cs.uiuc.edu/mailman/listinfo/llvmdev
>>
>
> _______________________________________________
> LLVM Developers mailing list
> LLVMdev at cs.uiuc.edu http://llvm.cs.uiuc.edu
> http://lists.cs.uiuc.edu/mailman/listinfo/llvmdev
>
>
> Can you compare ReST to docbook? We've talked about using docbook for > a long time. What are the pros and cons of each?I have no experience with DocBook, but it seems that since it is XML-based it should also suffer from verbosity issues. For example, the Boost project, which originally used plain DocBook, decided to build a new ReST-like documentation format[1] on top of it. [1] http://www.boost.org/doc/libs/1_37_0/doc/html/quickbook.html