Recent Changes - Search:

Softwares

.

Getting-Started-on-Documentaion-with-python-Sphinx

Main.Getting-Started-on-Documentaion-with-python-Sphinx History

Hide minor edits - Show changes to markup

November 05, 2014, at 10:12 AM by 122.171.107.88 -
Changed lines 369-420 from:

@]

to:

mint@mint ~/tmp/tutorial $ cp getting_started.rst /home/mint/Documents/www/ _build/ index.rst Makefile _templates/ conf.py make.bat _static/ mint@mint ~/tmp/tutorial $ cp getting_started.rst /home/mint/Documents/www/ mint@mint ~/tmp/tutorial $ cp _static/basic_screenshot.png /home/mint/Documents/www/_static/ mint@mint ~/tmp/tutorial $ cd /home/mint/Documents/www/ mint@mint ~/Documents/www $ ll total 56 drwxr-xr-x 5 mint mint 4096 Nov 5 15:35 . drwxr-xr-x 4 mint mint 4096 Nov 5 15:09 .. drwxr-xr-x 4 mint mint 4096 Nov 5 15:16 _build -rw-r--r-- 1 mint mint 9012 Nov 5 15:14 conf.py -rw-r--r-- 1 mint mint 3178 Nov 5 15:35 getting_started.rst -rw-r--r-- 1 mint mint 456 Nov 5 15:14 index.rst -rw-r--r-- 1 mint mint 7260 Nov 5 15:14 make.bat -rw-r--r-- 1 mint mint 7080 Nov 5 15:14 Makefile drwxr-xr-x 2 mint mint 4096 Nov 5 15:36 _static drwxr-xr-x 2 mint mint 4096 Nov 5 15:14 _templates mint@mint ~/Documents/www $ vi index.rst mint@mint ~/Documents/www $ make html sphinx-build -b html -d _build/doctrees . _build/html Running Sphinx v1.3b1 loading pickled environment... done building [mo]: targets for 0 po files that are out of date building [html]: targets for 1 source files that are out of date updating environment: 1 added, 1 changed, 0 removed reading sources... [100%] index looking for now-outdated files... none found pickling environment... done checking consistency... done preparing documents... done writing output... [100%] index /home/mint/Documents/www/getting_started.rst:102: WARNING: undefined label: custom_look (if the link has no caption the label must precede a section header) generating indices... genindex writing additional pages... search copying images... [100%] _static/basic_screenshot.png copying static files... done copying extra files... done dumping search index in English (code: en) ... done dumping object inventory... done build succeeded, 1 warning.

Build finished. The HTML pages are in _build/html. mint@mint ~/Documents/www $

@]

REF:

http://stackoverflow.com/questions/4547849/good-examples-of-python-docstrings-for-sphinx

November 05, 2014, at 09:54 AM by 122.171.107.88 -
Added lines 341-368:

mint@mint ~/Documents/www $ make html sphinx-build -b html -d _build/doctrees . _build/html Running Sphinx v1.3b1 making output directory... loading pickled environment... not yet created building [mo]: targets for 0 po files that are out of date building [html]: targets for 1 source files that are out of date updating environment: 1 added, 0 changed, 0 removed reading sources... [100%] index looking for now-outdated files... none found pickling environment... done checking consistency... done preparing documents... done writing output... [100%] index generating indices... genindex writing additional pages... search copying static files... done copying extra files... done dumping search index in English (code: en) ... done dumping object inventory... done build succeeded.

Build finished. The HTML pages are in _build/html. mint@mint ~/Documents/www $

November 05, 2014, at 09:45 AM by 122.171.107.88 -
Added lines 256-340:

mint@mint ~/Documents/www $ sphinx-quickstart Welcome to the Sphinx 1.3b1 quickstart utility.

Please enter values for the following settings (just press Enter to accept a default value, if one is given in brackets).

Enter the root path for documentation. > Root path for the documentation [.]:

You have two options for placing the build directory for Sphinx output. Either, you use a directory "_build" within the root path, or you separate "source" and "build" directories within the root path. > Separate source and build directories (y/n) [n]:

Inside the root directory, two more directories will be created; "_templates" for custom HTML templates and "_static" for custom stylesheets and other static files. You can enter another prefix (such as ".") to replace the underscore. > Name prefix for templates and static dir [_]:

The project name will occur in several places in the built documentation. > Project name: Tutorials & Howto > Author name(s): Webmaster

Sphinx has the notion of a "version" and a "release" for the software. Each version can have multiple releases. For example, for Python the version is something like 2.5 or 3.0, while the release is something like 2.5.1 or 3.0a1. If you don't need this dual structure, just set both to the same value. > Project version: 1.0.0 > Project release [1.0.0]:

If the documents are to be written in a language other than English, you can select a language here by its language code. Sphinx will then translate text that it generates into that language.

For a list of supported codes, see http://sphinx-doc.org/config.html#confval-language. > Project language [en]:

The file name suffix for source files. Commonly, this is either ".txt" or ".rst". Only files with this suffix are considered documents. > Source file suffix [.rst]:

One document is special in that it is considered the top node of the "contents tree", that is, it is the root of the hierarchical structure of the documents. Normally, this is "index", but if your "index" document is a custom template, you can also set this to another filename. > Name of your master document (without suffix) [index]:

Sphinx can also add configuration for epub output: > Do you want to use the epub builder (y/n) [n]:

Please indicate if you want to use one of the following Sphinx extensions: > autodoc: automatically insert docstrings from modules (y/n) [n]: > doctest: automatically test code snippets in doctest blocks (y/n) [n]: ) [n]: sphinx: link between Sphinx documentation of different projects (y/n)

todo
write "todo" entries that can be shown or hidden on build (y/n) [n]:

> coverage: checks for documentation coverage (y/n) [n]: > pngmath: include math, rendered as PNG images (y/n) [n]: > mathjax: include math, rendered in the browser by MathJax (y/n) [n]: n]: config: conditional inclusion of content based on config values (y/n) [n y/n) [n]: : include links to the source code of documented Python objects (y

A Makefile and a Windows command file can be generated for you so that you only have to run e.g. `make html' instead of invoking sphinx-build directly. > Create Makefile? (y/n) [y]: > Create Windows command file? (y/n) [y]:

Creating file ./conf.py. Creating file ./index.rst. Creating file ./Makefile. Creating file ./make.bat.

Finished: An initial directory structure has been created.

You should now populate your master file ./index.rst and create other documentation source files. Use the Makefile to build the docs, like so:

   make builder

where "builder" is one of the supported builders, e.g. html, latex or linkcheck.

mint@mint ~/Documents/www $ ls _build conf.py index.rst make.bat Makefile _static _templates mint@mint ~/Documents/www $ sphinx-quickstart

November 05, 2014, at 09:37 AM by 122.171.107.88 -
Added lines 138-254:

mint ~ # easy_install -U sphinx Searching for sphinx Reading https://pypi.python.org/simple/sphinx/ Best match: Sphinx 1.3b1 Downloading https://pypi.python.org/packages/source/S/Sphinx/Sphinx-1.3b1.tar.gz#md5=c9be45edbec48f4e4e7cfc53831c2225 Processing Sphinx-1.3b1.tar.gz Writing /tmp/easy_install-o35U8W/Sphinx-1.3b1/setup.cfg Running Sphinx-1.3b1/setup.py -q bdist_egg --dist-dir /tmp/easy_install-o35U8W/Sphinx-1.3b1/egg-dist-tmp-RPWPdn no previously-included directories found matching 'doc/_build' Adding Sphinx 1.3b1 to easy-install.pth file Installing sphinx-apidoc script to /usr/local/bin Installing sphinx-build script to /usr/local/bin Installing sphinx-quickstart script to /usr/local/bin Installing sphinx-autogen script to /usr/local/bin

Installed /usr/local/lib/python2.7/dist-packages/Sphinx-1.3b1-py2.7.egg Processing dependencies for sphinx Searching for babel Reading https://pypi.python.org/simple/babel/ Best match: Babel 1.3 Downloading https://pypi.python.org/packages/source/B/Babel/Babel-1.3.tar.gz#md5=5264ceb02717843cbc9ffce8e6e06bdb Processing Babel-1.3.tar.gz Writing /tmp/easy_install-bPq_To/Babel-1.3/setup.cfg Running Babel-1.3/setup.py -q bdist_egg --dist-dir /tmp/easy_install-bPq_To/Babel-1.3/egg-dist-tmp-XRUxDJ warning: no previously-included files matching '*' found under directory 'docs/_build' warning: no previously-included files matching '*.pyc' found under directory 'tests' warning: no previously-included files matching '*.pyo' found under directory 'tests' Adding Babel 1.3 to easy-install.pth file Installing pybabel script to /usr/local/bin

Installed /usr/local/lib/python2.7/dist-packages/Babel-1.3-py2.7.egg Searching for snowballstemmer>=1.1 Reading https://pypi.python.org/simple/snowballstemmer/ Best match: snowballstemmer 1.2.0 Downloading https://pypi.python.org/packages/source/s/snowballstemmer/snowballstemmer-1.2.0.tar.gz#md5=51f2ef829db8129dd0f2354f0b209970 Processing snowballstemmer-1.2.0.tar.gz Writing /tmp/easy_install-yTMwS5/snowballstemmer-1.2.0/setup.cfg Running snowballstemmer-1.2.0/setup.py -q bdist_egg --dist-dir /tmp/easy_install-yTMwS5/snowballstemmer-1.2.0/egg-dist-tmp-Fr9R8u warning: no files found matching '*.py' under directory 'src' zip_safe flag not set; analyzing archive contents... Adding snowballstemmer 1.2.0 to easy-install.pth file

Installed /usr/local/lib/python2.7/dist-packages/snowballstemmer-1.2.0-py2.7.egg Searching for docutils>=0.10 Reading https://pypi.python.org/simple/docutils/ Best match: docutils 0.12 Downloading https://pypi.python.org/packages/source/d/docutils/docutils-0.12.tar.gz#md5=4622263b62c5c771c03502afa3157768 Processing docutils-0.12.tar.gz Writing /tmp/easy_install-cKeiBg/docutils-0.12/setup.cfg Running docutils-0.12/setup.py -q bdist_egg --dist-dir /tmp/easy_install-cKeiBg/docutils-0.12/egg-dist-tmp-4I75YD warning: no files found matching 'MANIFEST' warning: no files found matching '*' under directory 'extras' warning: no previously-included files matching '.cvsignore' found under directory '*' warning: no previously-included files matching '*.pyc' found under directory '*' warning: no previously-included files matching '*~' found under directory '*' warning: no previously-included files matching '.DS_Store' found under directory '*' zip_safe flag not set; analyzing archive contents... docutils.writers.docutils_xml: module references __path__ docutils.writers.latex2e.__init__: module references __file__ docutils.writers.pep_html.__init__: module references __file__ docutils.writers.html4css1.__init__: module references __file__ docutils.writers.s5_html.__init__: module references __file__ docutils.writers.odf_odt.__init__: module references __file__ docutils.parsers.rst.directives.misc: module references __file__ Adding docutils 0.12 to easy-install.pth file Installing rst2xml.py script to /usr/local/bin Installing rst2odt_prepstyles.py script to /usr/local/bin Installing rst2odt.py script to /usr/local/bin Installing rstpep2html.py script to /usr/local/bin Installing rst2xetex.py script to /usr/local/bin Installing rst2pseudoxml.py script to /usr/local/bin Installing rst2latex.py script to /usr/local/bin Installing rst2s5.py script to /usr/local/bin Installing rst2html.py script to /usr/local/bin Installing rst2man.py script to /usr/local/bin

Installed /usr/local/lib/python2.7/dist-packages/docutils-0.12-py2.7.egg Searching for Pygments>=1.2 Reading https://pypi.python.org/simple/Pygments/ Best match: Pygments 2.0rc1 Downloading https://pypi.python.org/packages/source/P/Pygments/Pygments-2.0rc1.tar.gz#md5=4a88a7c0d81e5bb74c011aaa04d114a3 Processing Pygments-2.0rc1.tar.gz Writing /tmp/easy_install-fJOWT0/Pygments-2.0rc1/setup.cfg Running Pygments-2.0rc1/setup.py -q bdist_egg --dist-dir /tmp/easy_install-fJOWT0/Pygments-2.0rc1/egg-dist-tmp-VRBXGx Adding Pygments 2.0rc1 to easy-install.pth file Installing pygmentize script to /usr/local/bin

Installed /usr/local/lib/python2.7/dist-packages/Pygments-2.0rc1-py2.7.egg Searching for Jinja2>=2.3 Reading https://pypi.python.org/simple/Jinja2/ Best match: Jinja2 2.7.3 Downloading https://pypi.python.org/packages/source/J/Jinja2/Jinja2-2.7.3.tar.gz#md5=b9dffd2f3b43d673802fe857c8445b1a Processing Jinja2-2.7.3.tar.gz Writing /tmp/easy_install-uBSEUF/Jinja2-2.7.3/setup.cfg Running Jinja2-2.7.3/setup.py -q bdist_egg --dist-dir /tmp/easy_install-uBSEUF/Jinja2-2.7.3/egg-dist-tmp-bHFA4W warning: no files found matching '*' under directory 'custom_fixers' warning: no previously-included files matching '*' found under directory 'docs/_build' warning: no previously-included files matching '*.pyc' found under directory 'jinja2' warning: no previously-included files matching '*.pyc' found under directory 'docs' warning: no previously-included files matching '*.pyo' found under directory 'jinja2' warning: no previously-included files matching '*.pyo' found under directory 'docs' Adding Jinja2 2.7.3 to easy-install.pth file

Installed /usr/local/lib/python2.7/dist-packages/Jinja2-2.7.3-py2.7.egg Searching for pytz>=0a Reading https://pypi.python.org/simple/pytz/ Best match: pytz 2014.9 Downloading https://pypi.python.org/packages/2.7/p/pytz/pytz-2014.9-py2.7.egg#md5=b8149d1f94d12b402ac6e27a7b12353b Processing pytz-2014.9-py2.7.egg Moving pytz-2014.9-py2.7.egg to /usr/local/lib/python2.7/dist-packages Adding pytz 2014.9 to easy-install.pth file

Installed /usr/local/lib/python2.7/dist-packages/pytz-2014.9-py2.7.egg Finished processing dependencies for sphinx mint ~ #

November 05, 2014, at 09:33 AM by 122.171.107.88 -
Added lines 129-138:

mint ~ # python -c 'import sphinx' Traceback (most recent call last):

  File "<string>", line 1, in <module>

ImportError: No module named sphinx mint ~ # easy_install -U sphinx Searching for sphinx Reading https://pypi.python.org/simple/sphinx/

November 05, 2014, at 09:32 AM by 122.171.107.88 -
Added lines 1-129:

DRAFT DOC PLEASE IGNORE...

mint ~ # easy_install
The program 'easy_install' is currently not installed. You can install it by typing:
apt-get install python-setuptools
mint ~ # apt-get install python-setuptools
Reading package lists... Done
Building dependency tree       
Reading state information... Done
The following NEW packages will be installed:
  python-setuptools
0 upgraded, 1 newly installed, 0 to remove and 361 not upgraded.
Need to get 230 kB of archives.
After this operation, 830 kB of additional disk space will be used.
Get:1 http://archive.ubuntu.com/ubuntu/ trusty/main python-setuptools all 3.3-1ubuntu1 [230 kB]
Fetched 230 kB in 11s (19.5 kB/s)           
Selecting previously unselected package python-setuptools.
(Reading database ... 174074 files and directories currently installed.)
Preparing to unpack .../python-setuptools_3.3-1ubuntu1_all.deb ...
Unpacking python-setuptools (3.3-1ubuntu1) ...
Setting up python-setuptools (3.3-1ubuntu1) ...



mint ~ # dpkg -L python-setuptools
/.
/usr
/usr/lib
/usr/lib/python2.7
/usr/lib/python2.7/dist-packages
/usr/lib/python2.7/dist-packages/setuptools-3.3.egg-info
/usr/lib/python2.7/dist-packages/setuptools-3.3.egg-info/zip-safe
/usr/lib/python2.7/dist-packages/setuptools-3.3.egg-info/PKG-INFO
/usr/lib/python2.7/dist-packages/setuptools-3.3.egg-info/requires.txt
/usr/lib/python2.7/dist-packages/setuptools-3.3.egg-info/dependency_links.txt
/usr/lib/python2.7/dist-packages/setuptools-3.3.egg-info/entry_points.txt
/usr/lib/python2.7/dist-packages/setuptools-3.3.egg-info/SOURCES.txt
/usr/lib/python2.7/dist-packages/setuptools-3.3.egg-info/top_level.txt
/usr/lib/python2.7/dist-packages/setuptools.pth
/usr/lib/python2.7/dist-packages/_markerlib
/usr/lib/python2.7/dist-packages/_markerlib/markers.py
/usr/lib/python2.7/dist-packages/_markerlib/__init__.py
/usr/lib/python2.7/dist-packages/setuptools
/usr/lib/python2.7/dist-packages/setuptools/tests
/usr/lib/python2.7/dist-packages/setuptools/tests/environment.py
/usr/lib/python2.7/dist-packages/setuptools/tests/test_develop.py
/usr/lib/python2.7/dist-packages/setuptools/tests/test_build_ext.py
/usr/lib/python2.7/dist-packages/setuptools/tests/py26compat.py
/usr/lib/python2.7/dist-packages/setuptools/tests/test_dist_info.py
/usr/lib/python2.7/dist-packages/setuptools/tests/script-with-bom.py
/usr/lib/python2.7/dist-packages/setuptools/tests/test_svn.py
/usr/lib/python2.7/dist-packages/setuptools/tests/doctest.py
/usr/lib/python2.7/dist-packages/setuptools/tests/test_test.py
/usr/lib/python2.7/dist-packages/setuptools/tests/test_upload_docs.py
/usr/lib/python2.7/dist-packages/setuptools/tests/test_find_packages.py
/usr/lib/python2.7/dist-packages/setuptools/tests/test_markerlib.py
/usr/lib/python2.7/dist-packages/setuptools/tests/test_sdist.py
/usr/lib/python2.7/dist-packages/setuptools/tests/test_egg_info.py
/usr/lib/python2.7/dist-packages/setuptools/tests/__init__.py
/usr/lib/python2.7/dist-packages/setuptools/tests/test_sandbox.py
/usr/lib/python2.7/dist-packages/setuptools/tests/server.py
/usr/lib/python2.7/dist-packages/setuptools/tests/test_bdist_egg.py
/usr/lib/python2.7/dist-packages/setuptools/tests/test_easy_install.py
/usr/lib/python2.7/dist-packages/setuptools/tests/test_packageindex.py
/usr/lib/python2.7/dist-packages/setuptools/tests/test_resources.py
/usr/lib/python2.7/dist-packages/setuptools/dist.py
/usr/lib/python2.7/dist-packages/setuptools/py26compat.py
/usr/lib/python2.7/dist-packages/setuptools/compat.py
/usr/lib/python2.7/dist-packages/setuptools/depends.py
/usr/lib/python2.7/dist-packages/setuptools/site-patch.py
/usr/lib/python2.7/dist-packages/setuptools/py27compat.py
/usr/lib/python2.7/dist-packages/setuptools/archive_util.py
/usr/lib/python2.7/dist-packages/setuptools/lib2to3_ex.py
/usr/lib/python2.7/dist-packages/setuptools/package_index.py
/usr/lib/python2.7/dist-packages/setuptools/extension.py
/usr/lib/python2.7/dist-packages/setuptools/__init__.py
/usr/lib/python2.7/dist-packages/setuptools/sandbox.py
/usr/lib/python2.7/dist-packages/setuptools/py31compat.py
/usr/lib/python2.7/dist-packages/setuptools/script template (dev).py
/usr/lib/python2.7/dist-packages/setuptools/script template.py
/usr/lib/python2.7/dist-packages/setuptools/ssl_support.py
/usr/lib/python2.7/dist-packages/setuptools/command
/usr/lib/python2.7/dist-packages/setuptools/command/saveopts.py
/usr/lib/python2.7/dist-packages/setuptools/command/bdist_wininst.py
/usr/lib/python2.7/dist-packages/setuptools/command/alias.py
/usr/lib/python2.7/dist-packages/setuptools/command/bdist_rpm.py
/usr/lib/python2.7/dist-packages/setuptools/command/sdist.py
/usr/lib/python2.7/dist-packages/setuptools/command/egg_info.py
/usr/lib/python2.7/dist-packages/setuptools/command/bdist_egg.py
/usr/lib/python2.7/dist-packages/setuptools/command/__init__.py
/usr/lib/python2.7/dist-packages/setuptools/command/upload_docs.py
/usr/lib/python2.7/dist-packages/setuptools/command/install_egg_info.py
/usr/lib/python2.7/dist-packages/setuptools/command/build_ext.py
/usr/lib/python2.7/dist-packages/setuptools/command/test.py
/usr/lib/python2.7/dist-packages/setuptools/command/setopt.py
/usr/lib/python2.7/dist-packages/setuptools/command/build_py.py
/usr/lib/python2.7/dist-packages/setuptools/command/easy_install.py
/usr/lib/python2.7/dist-packages/setuptools/command/install.py
/usr/lib/python2.7/dist-packages/setuptools/command/develop.py
/usr/lib/python2.7/dist-packages/setuptools/command/install_scripts.py
/usr/lib/python2.7/dist-packages/setuptools/command/register.py
/usr/lib/python2.7/dist-packages/setuptools/command/install_lib.py
/usr/lib/python2.7/dist-packages/setuptools/command/rotate.py
/usr/lib/python2.7/dist-packages/setuptools/script
/usr/lib/python2.7/dist-packages/setuptools/svn_utils.py
/usr/lib/python2.7/dist-packages/setuptools/version.py
/usr/lib/python2.7/dist-packages/easy_install.py
/usr/share
/usr/share/doc
/usr/share/doc/python-setuptools
/usr/share/doc/python-setuptools/index.txt
/usr/share/doc/python-setuptools/python3.txt.gz
/usr/share/doc/python-setuptools/merge.txt.gz
/usr/share/doc/python-setuptools/setuptools.txt.gz
/usr/share/doc/python-setuptools/releases.txt
/usr/share/doc/python-setuptools/using.txt
/usr/share/doc/python-setuptools/copyright
/usr/share/doc/python-setuptools/merge-faq.txt.gz
/usr/share/doc/python-setuptools/easy_install.txt.gz
/usr/share/doc/python-setuptools/formats.txt.gz
/usr/share/doc/python-setuptools/development.txt
/usr/share/doc/python-setuptools/roadmap.txt
/usr/bin
/usr/bin/easy_install
/usr/bin/easy_install-2.7
/usr/share/doc/python-setuptools/changelog.Debian.gz
mint ~ # dpkg -L python-setuptools
Edit - History - Print - Recent Changes - Search
Page last modified on November 05, 2014, at 10:12 AM