Subject: Re: [OMPI docs] Docs suggestions
From: Shao-Ching Huang (huangsc_at_[hidden])
Date: 2013-09-24 20:38:07
There are some projects using sphinx:
http://docs.openstack.org/developer/swift/
http://fenicsproject.org/
http://ipython.org/
Authors write plain text that looks like this (without the HTML tags
explicitly):
https://bitbucket.org/fenics-project/fenics-web/raw/262ac46e900d3ed81fb01e7c8efb050be9c70d9b/source/documentation/tutorial/materials.rst
One useful feature of a system like Sphinx is, like latex, it can
automatically generates links and indices across source files.
IMHO, there is probably no perfect solution in choosing a source
format. If the OpenMPI docs project is to be a collaborative effort,
it may be useful to pick a format/system that is easy to
write/contribute/maintain among OpenMPI users (I suppose many of them
are computational/application scientists who may have deep knowledge
in MPI/OpenMPI but not necessarily so in web site rendering).
Something can can support a document consisting of multiple chapters
(think latex "book" class), can easily output (reasonably modern-look)
HTML for web viewing, can generate a PDF for offline reading,
somewhat-"easy"-to-write source format, in plain text files (version
control), automatic index/cross-link (think latex "label") generation,
would be a good candidate.
Thanks,
Shao-Ching
On Tue, Sep 24, 2013 at 2:47 PM, Kelly Black <kjblack_at_[hidden]> wrote:
> Hello,
>
> If you want output in HTML then just using HTML is a good choice. It would
> be relatively straightforward to use a template system to make it easier to
> maintain and ensure uniformity over multiple pages with options for
> different page lengths. Working in HTML is relatively straight forward and
> there are multiple choices with respect to authoring tools to appeal to more
> people.
>
> It is a good idea to make the Open MPI aspects the primary material for the
> document. I think it is important to have the simple examples and broad
> overview of MPI programming. I recently came back to MPI after a long
> hiatus, and I found it difficult to find good material to get started. I
> ended up having to collect material from a wide variety of sources which was
> frustrating.
>
> -Kel
>
> _______________________________________________________
> Kelly Black Phone: (315) 600-8334
> Clarkson University Fax: (315) 268-2371
> Department of Math. & C.S.
> PO Box 5815
> Potsdam, NY 13699-5815
> USA
>
>
> On Tue, Sep 24, 2013 at 2:42 PM, <manday_at_[hidden]> wrote:
>>
>> Sphinx is one of the most awful and dysfunctional documentation systems
>> that I've ever seen. Admitted, I only had to deal with it in the context
>> of Python and associates, but that was enough to seriously traumatize
>> me.
>>
>> Considering documentation, your primary concern should be that of
>> finding a powerful and yet easy-to-write markup language. Presentation
>> is a subordinate matter - tools like pandoc will eventually always allow
>> you to render any kind of presentation you prefer.
>>
>> In my opinion, HTML and EPUB are the best things we have for writing
>> technical documents at the moment. EPUB still suffers from not being
>> able to display mathematical contents, but that should be of little
>> meaning for OpenMPI. HTML5 on the other hand, is a bit lacking with
>> regard to defining meta data.
>>
>> Writing HTML isn't that bad. It may be not as convenient as writing TeX,
>> but it offers the considerable advantage of being a clearly structured
>> and readily available markup language.
>>
>> I've had only good experiences writing documents in HTML5, so if I were
>> to give a vote, I'd opt for HTML.
>>
>> On Tue, Sep 24, 2013 at 09:53:06AM -0700, Shao-Ching Huang wrote:
>> > Hi,
>> >
>> > Regarding the source format, if LaTeX is out of the table, may I
>> > suggest Sphinx, http://sphinx-doc.org/. Sphinx can generate outputs in
>> > HTML, latex, texinfo, pdf, etc. formats. The source is mostly
>> > reStructuredText, so like asciidoc and markdown, it is less burden for
>> > writers. Embedded code examples can be highlighted by pygment
>> > (http://pygments.org/).
>> >
>> > Shao-Ching Huang
>> >
>> >
>> > On Tue, Sep 24, 2013 at 9:07 AM, Jeff Squyres (jsquyres)
>> > <jsquyres_at_[hidden]> wrote:
>> > > On the weekly Open MPI engineering call today, we talked about the
>> > > docs project.
>> > >
>> > > The developer community had a few suggestions:
>> > >
>> > > 1. Affirmation of focusing on user-level documentation of Open
>> > > MPI-specific issues. E.g., here's how OMPI's wrapper compilers work; here's
>> > > how to use --showme, here's how to use OMPI's mpirun, here's how to set OMPI
>> > > MCA params, ...etc. A short MPI programming tutorial would be ok, but keep
>> > > it short/high level, and use it as a gateway to explaining the OMPI tools
>> > > surrounding an MPI source code (because there's books and lots of google
>> > > material on writing MPI code).
>> > >
>> > > 2. Additionally, try to make docs that can be fairly stable over time:
>> > > stuff that won't need to be updated frequently, because documentation tends
>> > > to suffer from bit rot. So if we can intentionally write fairly stable docs
>> > > to start with, they'll have a longer shelf life.
>> > >
>> > > Meaning: don't document every OMPI detail. Rather, (at least to start
>> > > with) document all the high-level OMPI concepts that haven't changed in a
>> > > long time: ./configure && make -j 32 install, wrapper compilers, mpirun, MCA
>> > > params, etc.
>> > >
>> > > 3. The community suggested that PDF might not be a good primary format
>> > > (this surprised me). For example, Google scores PDFs lower than HTML --
>> > > that's a good point; I didn't know that.
>> > >
>> > > Put differently: apparently, kids these days want to read web pages,
>> > > not PDFs. So the question naturally of source code format was raised -- the
>> > > old "latex can render into both PDF and HTML" issue came up. I don't know
>> > > if anyone has tried it recently, but the HTML emitted by latex2html is
>> > > actually pretty awful/horrible/ugly. Some suggestions were floated that
>> > > might be good instead of latex (because they can render
>> > >
>> > > - Asciidoc, which renders to both HTML and PDF (and others),
>> > > http://www.methods.co.nz/asciidoc/
>> > >
>> > > - Pandoc, which will let you convert arbitrarily between different
>> > > markup/markdown formats: http://johnmacfarlane.net/pandoc/
>> > >
>> > > - Markdown, a markup language:
>> > > http://daringfireball.net/projects/markdown/ (probably need to route through
>> > > Pandoc to get PDF from Markdown)
>> > >
>> > > - Docbook, but that's basically writing XML, which feels kinda
>> > > ugly/blech.
>> > >
>> > > Thoughts?
>> > >
>> > > --
>> > > Jeff Squyres
>> > > jsquyres_at_[hidden]
>> > > For corporate legal information go to:
>> > > http://www.cisco.com/web/about/doing_business/legal/cri/
>> > >
>> > > _______________________________________________
>> > > docs mailing list
>> > > docs_at_[hidden]
>> > > http://www.open-mpi.org/mailman/listinfo.cgi/docs
>> > _______________________________________________
>> > docs mailing list
>> > docs_at_[hidden]
>> > http://www.open-mpi.org/mailman/listinfo.cgi/docs
>> _______________________________________________
>> docs mailing list
>> docs_at_[hidden]
>> http://www.open-mpi.org/mailman/listinfo.cgi/docs
>
>
>
> _______________________________________________
> docs mailing list
> docs_at_[hidden]
> http://www.open-mpi.org/mailman/listinfo.cgi/docs