Subject: Re: [OMPI docs] Docs suggestions
From: Shao-Ching Huang (huangsc_at_[hidden])
Date: 2013-10-10 16:40:34
Looks good. Ready to go!
On Thu, Oct 10, 2013 at 10:43 AM, Kelly Black <kjblack_at_[hidden]> wrote:
>
> Dear Jeff,
>
> Thank you for posting the link. Sphinx can produce output in a wide
> variety of formats. I tried out the html and latexpdf options, and they
> looked reasonably good.
>
> With respect to the repo, there are now three branches. The master, and
> the development branch was created off of the master branch. I recently
> created the sphinx branch off of the development branch as a way to see
> what the sphinx output might look like. The sphinx branch has the most
> recent changes.
>
> 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 Thu, Oct 10, 2013 at 1:24 PM, Jeff Squyres (jsquyres) <
> jsquyres_at_[hidden]> wrote:
>
>> It's here:
>>
>> https://github.com/open-mpi/docs
>>
>> (I've been silently following this thread; I haven't tried Sphinx, but if
>> it can cross-render reasonable output, I'm in favor)
>>
>>
>> On Oct 10, 2013, at 1:07 PM, Shao-Ching Huang <huangsc_at_[hidden]> wrote:
>>
>> > Hi Kel,
>> >
>> > Thanks for organizing this. Please send the repo's URL when it is ready
>> to accept pull requests.
>> >
>> > Regards,
>> >
>> > Shao-Ching
>> >
>> >
>> > On Thu, Oct 10, 2013 at 6:07 AM, Kelly Black <kjblack_at_[hidden]> wrote:
>> > Dear Shao-Ching,
>> >
>> > Sorry for the delay in responding to this. I took some time play around
>> with sphinx and try some things with it. It is very easy to set up, and the
>> mark up language is easy to use. There are a few unhappy quirks, but
>> overall I kind of like it. It makes it easy to create large html documents
>> with cross referenced links.
>> >
>> > I made a new branch, sphinx, in the Open MPI document repo and have
>> converted the first two latex files over to rst format. It was a bit clumsy
>> at first as I learned some of the details, but I am happy with the results.
>> >
>> > I would like to just keep moving forward and use this to generate the
>> html.
>> >
>> > 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 Thu, Sep 26, 2013 at 3:46 PM, Shao-Ching Huang <huangsc_at_[hidden]>
>> wrote:
>> > 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
>> > >
>> > >
>> >
>> >
>> > _______________________________________________
>> > docs mailing list
>> > docs_at_[hidden]
>> > http://www.open-mpi.org/mailman/listinfo.cgi/docs
>>
>>
>> --
>> 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
>