Add infrastructure to build Sphinx API documentation #308
Conversation
bjackman
force-pushed
the
sphinx-docs
branch
6 times, most recently
from
d842461
to
06a62d1
Compare
|
Fixed the warnings that were causing Travis to say no. The "doc:" patches could probably be squashed together but I think it might be useful to have them separate so we can see the changes I made to the sphinx config that |
bjackman
force-pushed
the
sphinx-docs
branch
3 times, most recently
from
130c275
to
4d82ea2
Compare
|
You can see the results here: http://lisa-linux-integrated-system-analysis.readthedocs.io/en/latest/ Again, I haven't reviewed that output properly, that's a separate task. |
bjackman
force-pushed
the
sphinx-docs
branch
2 times, most recently
from
917a197
to
2129287
Compare
There was a problem hiding this comment.
We should probably merge these bits... sooner better then later...
I've give it a run on my machine and I've noticed that in the generated documentation we don't get pages for the wlgen module. Is that expected?
It would be also nice if, in the main page, we can have a sort of index section which points at least to:
the tutorial notebooks
the examples notebooks
the release notes notebooks
the tests folder
the benchmarks folder
(in the future) the scripts folder
doc/conf.py
Outdated
| # built documents. | ||
| # | ||
| # The short X.Y version. | ||
| version = '16.10' |
There was a problem hiding this comment.
Should we keep updating this by hand... or can it be automatically generated out of some git tag?
There was a problem hiding this comment.
I'd say we can generate it from the git tag. That means you won't get the version if you're using a tarball, but TBH if anyone does do that I wouldn't expect them to be compiling documentation themselves.
doc/conf.py
Outdated
|
|
||
| # General information about the project. | ||
| project = u'LISA' | ||
| copyright = u'2016, ARM-Software' |
There was a problem hiding this comment.
This has to be updated to 2017... the first release can be 17.04
|
Just noticed that this series should also add a patch which updates |
|
Yep, agreed on all points above. |
|
As @derkling said, I think it would be nice to have this merged into LISA, even if it is not entirely finished. Maybe simply update the .gitignore and give it a go ? |
To see this working: source init_env make -C doc/ html $browser doc/_build/html/index.html http://www.sphinx-doc.org/en/1.4.9/tutorial.html This was generated with sphinx-quickstart ans sphinx-apidoc
This reverts commit 1b42dd9b97cdbc43bde56038714c28c3a6ec13cc.
We don't use this and it produces a warning if the directory doesn't exist.
To use these sphinx references you need to use names that would be valid in the Python (after the required imports were added)
This is required by readthedocs.org
This means we can build the docs without sourcing init_env - this is useful for readthedocs.io where we don't get to specify arbitrary commands.
This uses git but falls back to "UNKNOWN_VERSION" if anything goes wrong (e.g. we aren't in a git repo). The rationale for this is that the person building the docs is proabably a LISA developer - they are very likely to be using git and should be checking the log from the doc build for errors.
|
Yep, I actually already updated the gitignore. The result here is far from perfect but I think we can still merge it and tweak afterwards. I've also done most of the work getting this build automatically and hosted on readthedocs. Due to the way readthedocs works, that will be much easier to finish once this PR is merged. I've added something to use git to get the version string. Not yet certain if that will work with CI/readthedocs so I've put it in a separate commit (separate commits are useful anyway so that we can see what we added and what was autogen'd by sphinx). |
|
Automatic version string LGTM, though Travis weirdly fails on a warning not doc-related: |
|
The story continues in #534 |
This is still slightly rough; the structure of the documentation can probably be improved and I haven't reviewed the entire HTML output. However this should be a proof of concept and provide a base for more complete documentation and automated hosting.
Included:
sphinx-quickstartandsphinx-apidoc. Unfortunately I didn't record the details of the process I used and it was quite a while ago. If we need that info I will just do it again. No need to really review this, just skim the files and see what got added and where.