CODEWITHSUNDEEP
pythonwindowsdocumentpython-sphinx
Hriju
Hriju

Reputation: 738

how to use sphinx document generator in windows?

I want to make a site using sphinx document generator. But my machine is windows. I cant find sufficient resources for windows. If anyone could suggest me a way to implement sphinx in windows would be a great help.

Thanks.

Upvotes: 0

Views: 6439

Answers (1)

MikeHunter
MikeHunter

Reputation: 4304

Sphinx works just fine on Windows. To get started, go to the Quickstart tutorial and follow the instructions. One thing I would add is make sure you answer "y" to the question that asks if you want to separate the build and source folders. This will make things more simple later.

If you want to use apidoc (I think you do), then can use the command-line tools in the Scripts folder of your Python install. Or you can write your own script. Below is one I wrote to get .rst files for some target modules:

files = [u'C:\\Work\\Scripts\\Grapher\\both_pyplot.py',
         u'C:\\Work\\Scripts\\Grapher\\colors_pyplot.py',
         u'C:\\Work\\Scripts\\Grapher\\dataEditor.pyw',
         u'C:\\Work\\Scripts\\Grapher\\grapher.pyw']

for d in ('pyfiles', 'rst_temp'):
    try:
        shutil.rmtree(d)
    except WindowsError:
        pass
    os.mkdir(d)

#copy, rename .pyw files to .py so sphinx will pick them up
for fn in files:
    fn2 = fn
    if fn.lower().endswith('.pyw'):
        fn2 = fn[:-1]
    shutil.copy2(fn, os.path.join('pyfiles', os.path.basename(fn2)))

#now send to apidoc
lst = [fn, '-o', 'rst_temp', 'pyfiles']  
from sphinx.apidoc import main
main(lst)


msg = ('Now copy the rst files you want documentation for from the '
      '"rst_temp" dir to the the "source" dir, edit the index.html file '
      'in the "source" dir, and run builder.py')
print msg

The apidoc extension does not recognize .pyw files, so this script copies target modules to a temporary location and renames them with a .py extension so apidoc can use them.

To build your project, you can run the make.bat file in your project folder (created when quickstart runs) or you can write your own script. Here's a sample (builder.py):

import sys, os
fn = __file__

sys.path.append(os.path.normpath('C:\\Work\\Scripts\\Grapher'))

lst = [fn, '-b', 'html', 'source', 'build']

from sphinx import main
main(lst)

Upvotes: 3

Related Questions