Change request #1261
Improve ctools Sphinx docs
| Status: | Closed | Start date: | 07/10/2014 | |
|---|---|---|---|---|
| Priority: | Normal | Due date: | ||
| Assigned To: |  Deil Christoph | % Done: | 100% | |
| Category: | - | |||
| Target version: | 1.0.0 | |||
| Duration: |
Description
This is a bunch of clean-ups and improvements (hopefully) to the ctools Sphinx docs:
- The repo no longer contains files in `doc/html` ... this is the docs build output folder and it should be possible to do `rm -r doc/html` to get a clean slate at any time.
To make this work I had to add the `rawfiles` Sphinx directive (a single small Python file) to copy over the few remaining raw html pages from `doc/source` to `doc/html` when running `make sphinx`. - Removed a few old hand-written `html` files which have been replaced by `rst` files already.
- Added `doxylink` to cross-link from the ctools Sphinx docs to the ctools Doxygen docs(as is alrealy merged for `gammalib`)
- Added `intersphinx_mapping` to cross-link from the ctools Sphinx docs to the Gammalib Sphinx docs (always points to the version on the web, not the developer’s machine)
You can review the changes here:
https://github.com/cdeil/ctools/compare/ctools:devel...doxylink
Recurrence
No recurrence.
Related issues
History
#1
Updated by Knödlseder Jürgen over 10 years ago
- Status changed from Pull request to Resolved
- % Done changed from 0 to 100
Merged into trunk.
#2
Updated by Knödlseder Jürgen over 10 years ago
- Status changed from Resolved to In Progress
- % Done changed from 100 to 80
This seems not to work. Here what I get when I type make sphinx:
Running Sphinx v1.2b1
WARNING: Python package `sphinxcontrib.doxylink` not found.
WARNING: Please install it to get fully-functional Sphinx docs.
WARNING: https://pypi.python.org/pypi/sphinxcontrib-doxylink
loading pickled environment... done
loading intersphinx inventory from http://gammalib.sourceforge.net/objects.inv...
building [html]: targets for 16 source files that are out of date
updating environment: [extensions changed] 16 added, 0 changed, 1 removed
reading sources... [100%] user_manual/plotting
/Users/jurgen/git/ctools/doc/source/user_manual/enhancing.rst:10: ERROR: Unknown interpreted text role "doxy".
/Users/jurgen/git/ctools/doc/source/user_manual/enhancing.rst:11: ERROR: Unknown interpreted text role "doxy".
/Users/jurgen/git/ctools/doc/source/user_manual/enhancing.rst:12: ERROR: Unknown interpreted text role "doxy".
looking for now-outdated files... none found
pickling environment... done
checking consistency... /Users/jurgen/git/ctools/doc/source/tools_reference.rst:: WARNING: document isn't included in any toctree
done
preparing documents... done
writing output... [100%] user_manual/reference
Exception occurred:
File "/Library/Python/2.6/site-packages/Sphinx-1.2b1-py2.6.egg/sphinx/builders/html.py", line 421, in get_doc_context
display_toc = (self.env.toc_num_entries[docname] > 1),
KeyError: u'user_manual/reference'
The full traceback has been saved in /var/folders/AB/ABl3ng7kEL8ekpJX54bhLE+++TI/-Tmp-/sphinx-err-gVt7T9.log, if you want to report the issue to the developers.
Please also report this if it was a user error, so that a better error message can be provided next time.
Either send bugs to the mailing list at <http://groups.google.com/group/sphinx-users/>,
or report them in the tracker at <http://bitbucket.org/birkenfeld/sphinx/issues/>. Thanks!
make: *** [sphinx] Error 1
#3
Updated by Knödlseder Jürgen over 10 years ago
- Target version changed from 3rd coding sprint to 00-08-00
#4
Updated by Knödlseder Jürgen about 10 years ago
- Target version changed from 00-08-00 to 1.0.0
#5
Updated by Knödlseder Jürgen almost 10 years ago
- Status changed from In Progress to Closed
- % Done changed from 80 to 100
The documentation is now at a reasonable level for the release.