Subject: Re: [OMPI docs] Docs suggestions
From: Shao-Ching Huang (huangsc_at_[hidden])
Date: 2013-09-26 15:46:01
Like many other systems, the conveniences of using Sphinx also come
with all the baggage it carries. It uses a certain template system. It
comes with a few certain default layouts ("themes",
http://sphinx-doc.org/theming.html). Many things are configurable, but
one will have to manipulate within Sphinx's framework.
My experiences with Sphinx are that if the what you want is close to
one of the default layouts, then things are really easy, time-saving
and smooth -- it allows you to totally focus on content texts in clean
plain texts and get good-looking "for free". On the other hand, if you
want a dramatically different layout, some hacking may be required.
Another possibility is just write in LaTeX (which seems to be the
original plan). If there are concerns about latex2html, how about
tex4ht (http://tug.org/applications/tex4ht/mn.html) which seems much
more flexible in controlling the HTML output? Any comments on this?
My sense is there is no one source format that will satisfy all
requirements. At some point, we will have to just pick up a reasonable
format and just start using it. Say, a few months into the project, if
the choice turns out to be really bad, it is not impossible to switch
with the help of some tools.
Shao-Ching
On Thu, Sep 26, 2013 at 11:26 AM, Kelly Black <kjblack_at_[hidden]> wrote:
> Hello,
>
> I just took a quick look at the documentation on Sphinx at their website.
> My first reaction is that it did not seem like something that would eat my
> cats and lay waste to the surrounding town. It seems to have the facilities
> to create a well structured system of documents, and the markeup appears to
> be relatively straight forward. Is there anything really wrong with it?
>
> Besides if we judged HTML by the documents some people create with it we
> would have banned it a long time ago.
>
> Sincerely,
> 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 8:38 PM, Shao-Ching Huang <huangsc_at_[hidden]> wrote:
>>
>> 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
>
>