Sphinx Documentation and Html page creation

$ sphinx-quickstart

follow command line for instructions
say yes to "autodoc" extension
also automatic api documentation generator called sphinx-apidoc

creates a source directory wiht a conf.py and a master document , index.rst (default)

place your files in the directory where the source directory and conf.py files are located

$ sphinx-build -b html courcedir builddir

sourcedir is the source directory, and builddir is the directory in which you want to place the built documentation -b option selects a builder (html for creating the web page)

In order for htis to work properly, you need to include all filepaths to all modules that you are using in the conf.py file that is generated. I used sys.path.insert(0, os.path.abspath('../pathtopyscript')) (had issues with the slicer import when running the sphinx html creation, so that was commented out, and then uncommented when files were generated.

You also need wrap the non function part of the python script you are generating the docs for with if __name__ == '__main__': , otherwise the call of make html will return an error of 'the module executes module level statement and it might call sys.exit().' , and the file will not build properly with the modules listed in the rst file.

For comments that you want included in the html file, that arent in the code (ie despcription and call examples) , you can do that in the index.rst file, which is used to generate the html for all modules using the sphinx format

if you use quickstart, this creates a makefile in which , in that case , all you need to call is

$ make html

to generate the html file (I am still trying to figure out how to access this. so far the autogeneration 
allows you to view the actaul page, which is generated as index.html, by rihgt clicking and then opening it 
in firefox

you can also generate pdf documents by calling 

$ make latexpdf

https://pythonhosted.org/an_example_pypi_project/sphinx.html

This is what the resulting html file will look like