Searchable online documentation

[drphilmarshall]

We talked about this in Phoenix - the idea was to fix up the docstrings in the contributed files so that they compile into some nice set of online documentation. Alex Kim suggested "readthedocs", there's also sphinx and doxygen that we could use to make pages served on the gh-pages of this repo. Implementing this early might help us with the organisation of the contributed code.

[RobertLuptonTheGood]

Let's not reinvent wheels. Or, rather, let's invent this wheel only once -- and I'm happy to have you do the inventing...

The project is thinking about how to improve our docs. We currently use doxygen which works OK for C++ but isn't a good solution for python (and I think that APIs modified in swig .i files are dropped on the floor entirely).

We'd like to move to sphinx, but integrated with doxygen in some way. There are ways that this can be managed (e.g. breathe) but we haven't had time to come up with a solution.

                        R

Phil Marshall wrote:

We talked about this in Phoenix - the idea was to fix up the docstrings in the contributed files so that they compile into some nice set of online documentation. Alex Kim suggested "readthedocs", there's also sphinx and doxygen that we could use to make pages served on the gh-pages of this repo. Implementing this early might help us with the organisation of the contributed code.

[RobertLuptonTheGood]

Let's not reinvent wheels. Or, rather, let's invent this wheel only once -- and I'm happy to have you do the inventing...

The Qserv team is already experimenting with sphinx.  Let's

coordinate all the inventors, lest we come up with multiple solutions.

Kian-Tat Lim, LSST Data Management, ktl@slac.stanford.edu

[RobertLuptonTheGood]

The OpSim team is also using sphinx.

I believe 'readthedocs' is basically a webhost for sphinx documentation .. they may do some additional "prettying up" of the output. This is only from a very initial skim of their homepage, though, so please chime in if you know better.

The OpSim team is using sphinx and hosting the resulting docs themselves (see http://www.noao.edu/lsst/opsim/docs/simulator/).

What are the qserv team doing?

Lynne

On Mon, Aug 18, 2014 at 9:21 AM, Kian-Tat Lim ktl@slac.stanford.edu wrote:

Let's not reinvent wheels. Or, rather, let's invent this wheel only once -- and I'm happy to have you do the inventing...

    The Qserv team is already experimenting with sphinx.  Let's

coordinate all the inventors, lest we come up with multiple solutions.

Kian-Tat Lim, LSST Data Management, ktl@slac.stanford.edu

---

LSST-data mailing list LSST-data@listserv.lsstcorp.org https://listserv.lsstcorp.org/mailman/listinfo/lsst-data

[rhiannonlynne]

We're moving towards numpy style docstrings, to be used with sphinx and readTheDocs in core sims_maf. We should do so in sims_maf_contrib as well! We do not have a 'live' read the docs version of the sims_maf documentation (yet) but if you clone the repo, then:

cd doc make html open build/html/index.html

Note that on el capitan, 'make' is by default in /usr/bin -- you will not be able to actually build the documentation, because it won't be able to find the libraries LSST adds to DYLD_LIBRARY_PATH. A quick and dirty way around this is to copy /usr/bin/make to somewhere else and run it from there. You probably don't want to do this as a normal procedure, but it'll work for now.

[rhiannonlynne]

We are working on documentation, but some is available at https://sims-maf.lsst.io/