Prepare the environment of Sphinx documentation (Issue 138) #34
Conversation
(Based on commands suggested by James on issue xapian#138 ) + Costumization of Project Name, Author, Version and Release
- Makefile, configuration file, index file - Remove the recent sh script, no need for creating the env each time
Since the getting started is using rst syntax so I integrated it with the API modules documentation. The user now can view all python docs in the same place I also add the examples code into documentation
+ Removing conf module from indexing
Listing by module is completely a mess, it shows irrelvant details and unsorted
| # The short X.Y version. | ||
| version = '1.3.1' | ||
| # The full version, including alpha/beta/rc tags. | ||
| release = '1.3.1' |
There was a problem hiding this comment.
We can't have hard-coded version numbers in scripts like this, or else they'll just end up out of date.
Either this file needs to be generated (adding a .in suffix and changing 1.3.1 to @VERSION@, and then adding it to the list of files in AC_CONFIG_FILES in configure.ac should do the trick, possibly plus a bit of work to support srcdir!=builddir), or else something like passing VERSION from the Makefile as a command line argument.
There was a problem hiding this comment.
done by passing @VERSION@
- Include examples from an separated files instead of write them directly - Fix an underlining of a title - Reduce max levels to 2 in table of contents
- Merging new sphinx based with the old one - updating the build
- Keep automated the generation of library members
- using sphinx
| -case "$@" in */*) d=`echo "$@"|sed 's,/[^/]*$$,,'`; test -d "$$d" || mkdir "$$d" ;; esac | ||
| $(RST2HTML) --exit-status=warning $< $@ | ||
| build-sphinx-doc: | ||
| export PYTHONPATH=$$PWD:$$PYTHONPATH;cd docs/; sphinx-build -b html -d _build/doctrees . _build/html |
There was a problem hiding this comment.
$PWD isn't portable (POSIX requires it, but traditional shells don't support it).
Using export and setting a value at the same time also isn't portable (again, POSIX requires it but older shells don't support it).
It's more robust to use && after the cd, so the rule fails if the docs directory doesn't exist rather than generating documentation in the wrong directory.
I'd also avoid the trailing slash on docs/ - some tools can be a bit fussy about them (especially on the commercial Unix platforms) - I don't recall particularly if cd dislikes them anywhere, but it seems cleaner without the slash anyway.
Putting that all together, my suggestion would be:
cd docs && PYTHONPATH=..:$$PYTHONPATH sphinx-build -b html -d _build/doctrees . _build/html
(A relative path in PYTHONPATH works, as we already use . in the run-python-test script.)
following olly comments: ============== $PWD isn't portable (POSIX requires it, but traditional shells don't support it). Using export and setting a value at the same time also isn't portable (again, POSIX requires it but older shells don't support it). It's more robust to use && after the cd, so the rule fails if the docs directory doesn't exist rather than generating documentation in the wrong directory. I'd also avoid the trailing slash on docs/ - some tools can be a bit fussy about them (especially on the commercial Unix platforms) - I don't recall particularly if cd dislikes them anywhere, but it seems cleaner without the slash anyway. Putting that all together, my suggestion would be: cd docs && PYTHONPATH=..:$$PYTHONPATH sphinx-build -b html -d _build/doctrees . _build/html (A relative path in PYTHONPATH works, as we already use . in the run-python-test script.) ===============
( remove an emptyline added by mistake in HACKING )
… different place to python(2)
+ no need to add docs/conf.py in EXTRA_DIST
| .rst.html: | ||
| -case "$@" in */*) d=`echo "$@"|sed 's,/[^/]*$$,,'`; test -d "$$d" || mkdir "$$d" ;; esac | ||
| $(RST2HTML) --exit-status=warning $< $@ | ||
| $(sphinxdocs): xapian/__init__.py docs/conf.py $(srcdir)/docs/*.rst $(dist_exampledata_DATA) |
There was a problem hiding this comment.
We really need a variable (e.g. RST_DOCS) which lists the actual rst sources, then use that here instead of the wildcard, and include $(RST_DOCS) in EXTRA_DIST above instead of just removing index.rst. Without the latter, the rst sources won't be included in the tarball of sources.
|
I fixed that in assem-ch@9f7b849 |
|
The wildcard part seems unchanged. |
|
I didnt get you |
|
Above I suggested that When srcdir != build, VPATH is set to |
|
check the last commit 5961c93 |
|
Thanks, merged via SVN. There was an inconsistency as to whether the Python3 introduction was called |
http://trac.xapian.org/ticket/138
You can browse how it looks here: http://xapian.alfanous.org/
what's next?
Dependencies:
python-sphinx