-
Notifications
You must be signed in to change notification settings - Fork 41
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Issue277 auto generate api documentation #280
Conversation
Codecov Report
@@ Coverage Diff @@
## master #280 +/- ##
=======================================
Coverage 99.31% 99.31%
=======================================
Files 52 52
Lines 2624 2624
=======================================
Hits 2606 2606
Misses 18 18 Continue to review full report at Codecov.
|
I tried running
This was after installing the new dependencies with |
The above error could be related to some version issues, see readthedocs/readthedocs.org#2569 Tried to fix by setting |
Tested this again. The
This was after running The HTML docs were generated but in practice they were pretty much empty because the docstrings couldn't be loaded due to the import errors. Anyway the next step would probably be to set up docs generation under ReadTheDocs (and possibly also Travis CI, by adding the necessary commands to |
The docs are now publicly available in in https://annif.readthedocs.io/en/latest/index.html. Currently all pushes to this branch (issue277-...) trigger building and publishing the docs. Travis is not involved in this, but the webhook system of readthedocs takes care of everything. TODO: Switch the trigger to listen to pushes to master (when this branch is ready to be merged, https://readthedocs.org/dashboard/annif/advanced/). Or, maybe the docs should be updated only on new release? Unfortunately, at the moment for building docs in readthedocs |
Maybe the import errors were due to Sphinx wrongly using Python2 for some reason, as this looks like. |
Excellent!
This is OK. We don't need to involve Travis here.
RTD docs are versioned, right? So it should be possible to have docs built both for the current
Would it be easy to add a rule to do this in the Makefile? The documentation should track changes in package/module structure as automatically as possible. I don't see a RTD config file included in the PR. Should we have one, even a minimal one? According to the link, "Using a configuration file is the recommended way of using Read the Docs."
Are you sure that we really need a |
I'll merge this now. I'm sure we can work out any outstanding issues in follow-up PRs. |
Thanks, good have this finished!
Yes, there's
NB: Done
You are right, there is an option for RTD builds which makes
I created a separate PR #285 for removing the unnecessary requirements files. One final point: @osma I think you too should have admin rights to the annif project in readthedocs. There is a user |
Initial auto-generated API documentation with Sphinx using readthedocs theme.
Running
make html
indocs/
createsdocs/_build/html
directory based on the.rst
files indocs/source
. Theindex.html
is the main page to start navigation.Currently there is essentially only autogenerated API information, just version number and few links in the index page are manually added. Should there be anything else at this point?
The
.rts
files are originally generated withsphinx-apidoc -o source/ ../annif
. Nowmake html
is enough to get additions and changes from source code docstrings to documentation.Edit: If a package/module is added, it is necessary to overwrite the existing
.rst
files by runningsphinx-apidoc -f -o source/ ../annif
indocs/
beforemake html
to get the changes.Uploading docs to readthedocs.io should be easy, they too are essentially running
make html
(the.rst
files need to be in the repository):https://docs.readthedocs.io/en/stable/builds.html#how-we-build-documentation
(closes #277 )