How to get Sphinx working with Jython on an unnetworked Windows 7 computer? - windows

Question

Once sphinx-apidoc has been run the command C:\path\to\doc\make html produces an error beginning:
The 'sphinx-build' command was not found [snip]
However the command does exist and the relevant environment variables are set.
More detail:
1 - Trying to run sphinx_apidoc:
'C:\path\to\jython\bin\sphinx-apidoc' is not recognised as an internal or external command
2 - Called using Jython works: jython C:\path\to\jython\bin\sphinx-apidoc with sensible options produces the documentation *.rst files, conf.py, etc files.
3 - make html then produces the following error:
The 'sphinx-build' command was not found [snip]
It then recommends setting the SPHINXBUILD environment variable, and even the PATH. I already have these two environment variables set, proven to myself by calling echo %PATH% and echo %SPHINXBUILD%.
This is where I get stuck. It appears that the files that Sphinx uses (sphinx-apidoc and sphinx-build in this case), which are in the C:\path\to\jython\bin\ directory, do not have any file suffixes. When called directly from Jython they work as expected (see point 2 above), however when called as part of another process (e.g. make html) they are not recognised and the execution fails (see points 1 and 3 above).
Does anyone know the what, why and most importantly 'how to fix' of this problem?
My setup process is on an unnetworked Windows 7 computer. Jython (2.5.2) was installed using the Jython installer. Then each of the following packages (except setuptools) was installed by extracting it locally and then running jython setup.py install in its extracted directory:
setuptools: by calling jython ez_setup.py with setuptools-1.4.2.tar.gz in the same directory (so there is no attempt to download it)
Jinja2 (2.5)
docutils (0.11)
Pygments (1.6)
Sphinx (1.2.1)
numpydoc (0.4) - Only mentioned because it is also isntalled on the machine.

Answer 1

I have managed to get it working. The problem was that the manual installation and the use of Jython meant that certain environment variables that were expected were not in place. Also, the use of Windows 7 (and I believe MS Windows in general) means that Python scripts without an extension cannot be run without calling them explicitly through Jython (Windows doesn't check for shebangs). Finally, file associations had not been set up (as happens automatically with CPython installation, but has not happened with Jython).
For anyone else with similar problems the following setup works for me:
Locations:
Java Runtime: C:\Java\jre7
Jython: C:\Jython\jython2.5.2
User Environment Variables:
JRE_HOME: C:\Java\jre7
JAVA_HOME: %JRE_HOME%
CLASSPATH: .
JYTHON_HOME: C:\Jython\jython2.5.2
PATH: %JRE_HOME%\bin;%JYTHON_HOME%\bin
File Associations:
At the command prompt type assoc .py=Python.File to associate 'Python.File' with the '.py' extension.
At the command prompt type ftype Python.File=C:\Jython\jython2.5.2\jython.bat "%1" %* to associate the Jython command with files of type 'Python.File'.
Append '.py' (;.PY) to the PATHEXT system environment variable. This will make it possible to execute Python files without having to provide their '.py' extension. (N.B. This does not make it possible to run Python files that do not have a '.py' extension.)
File Extensions:
Rename the four Sphinx commands to include '.py' extensions. This is remarkably difficult with vanilla Windows 7 as it does everything it can to distance the user from such 'low level' details as file extensions, however the rename command at the command prompt does the job: type ren sphinx* sphinx*.py when in the Jython bin directory.
It should now be possible to call sphinx-apidoc or similar from anywhere. Once this is complete the command make html, when called from the documentation directory, should work as expected.