overhaul the sphinx documentation

Sphinx:
* Build dir is now named `build` and the files are under `source`.
* MakeFile learned texinfo, info and gettext targets
* include __init__ documentation (autoclass_content)
* keep file ordering for methods (autodoc_member_order)
* comment out html_static_path to get rid of a warning

Doc:
* Index is now... an index! Takes advantage of :glob: to automatically
  create a complete table of content.
* Creates API reference which list the documentation directly from the
  jenkins/__init__.py file.  That will avoid the documentation duplication
  and some out of sync documentation.
* insert the module in the path to document it
* the example were both in index.rst and __init__.py create a new section
  with example.rst.  That can be later be improved with some typical use
  cases.
* A couple documentation update to some methods. The inline documentation
  was out of sync though the index.rst got updated.
This commit is contained in:
Antoine Musso 2013-04-13 23:59:59 +02:00
parent c3e23c2973
commit 170e878d2a
8 changed files with 123 additions and 243 deletions

View File

@ -5,14 +5,16 @@
SPHINXOPTS = SPHINXOPTS =
SPHINXBUILD = sphinx-build SPHINXBUILD = sphinx-build
PAPER = PAPER =
BUILDDIR = _build BUILDDIR = build
# Internal variables. # Internal variables.
PAPEROPT_a4 = -D latex_paper_size=a4 PAPEROPT_a4 = -D latex_paper_size=a4
PAPEROPT_letter = -D latex_paper_size=letter PAPEROPT_letter = -D latex_paper_size=letter
ALLSPHINXOPTS = -d $(BUILDDIR)/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) . ALLSPHINXOPTS = -d $(BUILDDIR)/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) source
# the i18n builder cannot share the environment and doctrees with the others
I18NSPHINXOPTS = $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) source
.PHONY: help clean html dirhtml singlehtml pickle json htmlhelp qthelp devhelp epub latex latexpdf text man changes linkcheck doctest .PHONY: help clean html dirhtml singlehtml pickle json htmlhelp qthelp devhelp epub latex latexpdf text man changes linkcheck doctest gettext
help: help:
@echo "Please use \`make <target>' where <target> is one of" @echo "Please use \`make <target>' where <target> is one of"
@ -29,6 +31,9 @@ help:
@echo " latexpdf to make LaTeX files and run them through pdflatex" @echo " latexpdf to make LaTeX files and run them through pdflatex"
@echo " text to make text files" @echo " text to make text files"
@echo " man to make manual pages" @echo " man to make manual pages"
@echo " texinfo to make Texinfo files"
@echo " info to make Texinfo files and run them through makeinfo"
@echo " gettext to make PO message catalogs"
@echo " changes to make an overview of all changed/added/deprecated items" @echo " changes to make an overview of all changed/added/deprecated items"
@echo " linkcheck to check all external links for integrity" @echo " linkcheck to check all external links for integrity"
@echo " doctest to run all doctests embedded in the documentation (if enabled)" @echo " doctest to run all doctests embedded in the documentation (if enabled)"
@ -100,7 +105,7 @@ latex:
latexpdf: latexpdf:
$(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex $(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex
@echo "Running LaTeX files through pdflatex..." @echo "Running LaTeX files through pdflatex..."
make -C $(BUILDDIR)/latex all-pdf $(MAKE) -C $(BUILDDIR)/latex all-pdf
@echo "pdflatex finished; the PDF files are in $(BUILDDIR)/latex." @echo "pdflatex finished; the PDF files are in $(BUILDDIR)/latex."
text: text:
@ -113,6 +118,24 @@ man:
@echo @echo
@echo "Build finished. The manual pages are in $(BUILDDIR)/man." @echo "Build finished. The manual pages are in $(BUILDDIR)/man."
texinfo:
$(SPHINXBUILD) -b texinfo $(ALLSPHINXOPTS) $(BUILDDIR)/texinfo
@echo
@echo "Build finished. The Texinfo files are in $(BUILDDIR)/texinfo."
@echo "Run \`make' in that directory to run these through makeinfo" \
"(use \`make info' here to do that automatically)."
info:
$(SPHINXBUILD) -b texinfo $(ALLSPHINXOPTS) $(BUILDDIR)/texinfo
@echo "Running Texinfo files through makeinfo..."
make -C $(BUILDDIR)/texinfo info
@echo "makeinfo finished; the Info files are in $(BUILDDIR)/texinfo."
gettext:
$(SPHINXBUILD) -b gettext $(I18NSPHINXOPTS) $(BUILDDIR)/locale
@echo
@echo "Build finished. The message catalogs are in $(BUILDDIR)/locale."
changes: changes:
$(SPHINXBUILD) -b changes $(ALLSPHINXOPTS) $(BUILDDIR)/changes $(SPHINXBUILD) -b changes $(ALLSPHINXOPTS) $(BUILDDIR)/changes
@echo @echo

View File

@ -1,217 +0,0 @@
Welcome to Python Jenkins's documentation!
==========================================
Python Jenkins is a library for the remote API of the `Jenkins
<http://jenkins-ci.org/>`_ continuous integration server. It is useful
for creating and managing jobs as well as build nodes.
Example usage::
j = jenkins.Jenkins('http://your_url_here', 'username', 'password')
j.get_jobs()
j.create_job('empty', jenkins.EMPTY_CONFIG_XML)
j.disable_job('empty')
j.copy_job('empty', 'empty_copy')
j.enable_job('empty_copy')
j.reconfig_job('empty_copy', jenkins.RECONFIG_XML)
j.delete_job('empty')
j.delete_job('empty_copy')
# build a parameterized job
j.build_job('api-test', {'param1': 'test value 1', 'param2': 'test value 2'})
build_info = j.get_build_info('build_name', next_build_number)
print(build_info)
Python Jenkins development is hosted on Launchpad: https://launchpad.net/python-jenkins
Installing
==========
``pip``::
pip install python-jenkins
``easy_install``::
easy_install python-jenkins
Ubuntu Oneiric or later::
apt-get install python-jenkins
API documentation
=================
.. class:: JenkinsException
General exception type for jenkins-API-related failures.
.. class:: Jenkins(url, [username=None, [password=None]])
Create handle to Jenkins instance.
All methods will raise :class:`JenkinsException` on failure.
:param username: Server username, ``str``
:param password: Server password, ``str``
:param url: URL of Jenkins server, ``str``
.. method:: get_jobs(self)
Get list of jobs running. Each job is a dictionary with
'name', 'url', and 'color' keys.
:returns: list of jobs, ``[ { str: str} ]``
.. method:: job_exists(name)
:param name: Name of Jenkins job, ``str``
:returns: ``True`` if Jenkins job exists
.. method:: build_job(name, [parameters=None, [token=None]])
Trigger build job.
:param parameters: parameters for job, or ``None``, ``dict``
.. method:: build_job_url(name, [parameters=None, [token=None]])
Get URL to trigger build job. Authenticated setups may require configuring a token on the server side.
:param parameters: parameters for job, or None., ``dict``
:param token: (optional) token for building job, ``str``
:returns: URL for building job
.. method:: create_job(name, config_xml)
Create a new Jenkins job
:param name: Name of Jenkins job, ``str``
:param config_xml: config file text, ``str``
.. method:: copy_job(from_name, to_name)
Copy a Jenkins job
:param from_name: Name of Jenkins job to copy from, ``str``
:param to_name: Name of Jenkins job to copy to, ``str``
.. method:: delete_job(name)
Delete Jenkins job permanently.
:param name: Name of Jenkins job, ``str``
.. method:: enable_job(name)
Enable Jenkins job.
:param name: Name of Jenkins job, ``str``
.. method:: disable_job(name)
Disable Jenkins job. To re-enable, call :meth:`Jenkins.enable_job`.
:param name: Name of Jenkins job, ``str``
.. method:: get_build_info(name, number)
Get build information dictionary.
:param name: Job name, ``str``
:param name: Build number, ``int``
:returns: dictionary of build information
.. method:: get_job_config(name) -> str
Get configuration XML of existing Jenkins job.
:param name: Name of Jenkins job, ``str``
:returns: Job configuration XML
.. method:: get_job_info(name)
Get job information dictionary.
:param name: Job name, ``str``
:returns: dictionary of job information
.. method:: debug_job_info(job_name)
Print out job info in more readable format
.. method:: reconfig_job(name, config_xml)
Change configuration of existing Jenkins job. To create a new job, see :meth:`Jenkins.create_job`.
:param name: Name of Jenkins job, ``str``
:param config_xml: New XML configuration, ``str``
.. method:: get_node_info(name) -> dict
Get node information dictionary
:param name: Node name, ``str``
:returns: Dictionary of node info, ``dict``
.. method:: node_exists(name) -> bool
:param name: Name of Jenkins node, ``str``
:returns: ``True`` if Jenkins node exists
.. method:: create_node(name, [numExecutors=2, [nodeDescription=None, [remoteFS='/var/lib/jenkins', [labels=None, [exclusive=False]]]]])
:param name: name of node to create, ``str``
:param numExecutors: number of executors for node, ``int``
:param nodeDescription: Description of node, ``str``
:param remoteFS: Remote filesystem location to use, ``str``
:param labels: Labels to associate with node, ``str``
:param exclusive: Use this node for tied jobs only, ``bool``
.. method:: delete_node(name)
Delete Jenkins node permanently.
:param name: Name of Jenkins node, ``str``
.. method:: get_queue_info(self)
:returns: list of job dictionaries, ``[dict]``
Example::
>>> queue_info = j.get_queue_info()
>>> print(queue_info[0])
{u'task': {u'url': u'http://your_url/job/my_job/', u'color': u'aborted_anime', u'name': u'my_job'}, u'stuck': False, u'actions': [{u'causes': [{u'shortDescription': u'Started by timer'}]}], u'buildable': False, u'params': u'', u'buildableStartMilliseconds': 1315087293316, u'why': u'Build #2,532 is already in progress (ETA:10 min)', u'blocked': True}
.. method:: get_info(self)
Get information on this Master. This information
includes job list and view information.
:returns: dictionary of information about Master, ``dict``
Example::
>>> info = j.get_info()
>>> jobs = info['jobs']
>>> print(jobs[0])
{u'url': u'http://your_url_here/job/my_job/', u'color': u'blue', u'name': u'my_job'}
.. method:: jenkins_open(req)
Utility routine for opening an HTTP request to a Jenkins server. This should only be used
to extends the :class:`Jenkins` API.
Indices and tables
==================
* :ref:`genindex`
* :ref:`modindex`
* :ref:`search`

8
doc/source/api.rst Normal file
View File

@ -0,0 +1,8 @@
:title: API reference
API reference
=============
.. automodule:: jenkins
:members:
:undoc-members:

View File

@ -15,12 +15,12 @@
import os import os
import sys import sys
sys.path.insert(0, os.path.abspath('..'))
# If extensions (or modules to document with autodoc) are in another directory, # If extensions (or modules to document with autodoc) are in another directory,
# add these directories to sys.path here. If the directory is relative to the # add these directories to sys.path here. If the directory is relative to the
# documentation root, use os.path.abspath to make it absolute, like shown here. # documentation root, use os.path.abspath to make it absolute, like shown here.
#sys.path.insert(0, os.path.abspath('.')) #sys.path.insert(0, os.path.abspath('.'))
sys.path.insert(0, os.path.abspath('../..'))
sys.path.insert(0, os.path.abspath('../../jenkins'))
# -- General configuration ---------------------------------------------------- # -- General configuration ----------------------------------------------------
@ -31,6 +31,12 @@ sys.path.insert(0, os.path.abspath('..'))
# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom ones. # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom ones.
extensions = ['sphinx.ext.autodoc'] extensions = ['sphinx.ext.autodoc']
# Also document __init__
autoclass_content = 'both'
# Change that to 'alphabetical' if you want
autodoc_member_order = 'bysource'
# Add any paths that contain templates here, relative to this directory. # Add any paths that contain templates here, relative to this directory.
templates_path = ['_templates'] templates_path = ['_templates']
@ -124,7 +130,7 @@ html_theme = 'default'
# Add any paths that contain custom static files (such as style sheets) here, # Add any paths that contain custom static files (such as style sheets) here,
# relative to this directory. They are copied after the builtin static files, # relative to this directory. They are copied after the builtin static files,
# so a file named "default.css" will overwrite the builtin "default.css". # so a file named "default.css" will overwrite the builtin "default.css".
html_static_path = ['_static'] #html_static_path = ['_static']
# If not '', a 'Last updated on:' timestamp is inserted at every page bottom, # If not '', a 'Last updated on:' timestamp is inserted at every page bottom,
# using the given strftime format. # using the given strftime format.

22
doc/source/example.rst Normal file
View File

@ -0,0 +1,22 @@
Example usage
=============
Example usage::
j = jenkins.Jenkins('http://your_url_here', 'username', 'password')
j.get_jobs()
j.create_job('empty', jenkins.EMPTY_CONFIG_XML)
j.disable_job('empty')
j.copy_job('empty', 'empty_copy')
j.enable_job('empty_copy')
j.reconfig_job('empty_copy', jenkins.RECONFIG_XML)
j.delete_job('empty')
j.delete_job('empty_copy')
# build a parameterized job
j.build_job('api-test', {'param1': 'test value 1', 'param2': 'test value 2'})
build_info = j.get_build_info('build_name', next_build_number)
print(build_info)
Look at the :doc:`api` for more details.

23
doc/source/index.rst Normal file
View File

@ -0,0 +1,23 @@
Welcome to Python Jenkins's documentation!
==========================================
Python Jenkins is a library for the remote API of the `Jenkins
<http://jenkins-ci.org/>`_ continuous integration server. It is useful
for creating and managing jobs as well as build nodes.
Table of content:
.. toctree::
:maxdepth: 2
:glob:
*
Python Jenkins development is hosted on Launchpad: https://launchpad.net/python-jenkins
Indices and tables
==================
* :ref:`genindex`
* :ref:`modindex`
* :ref:`search`

24
doc/source/install.rst Normal file
View File

@ -0,0 +1,24 @@
:title: Installing
Installing
==========
The module is known to pip and Debian based distribution as
``python-jenkins``.
``pip``::
pip install python-jenkins
``easy_install``::
easy_install python-jenkins
The module has been packaged since Ubuntu Oneiric (11.10)::
apt-get install python-jenkins
For developpement purpose you can get a fake module installed on your system
that will point to your working copy. Simply use::
python setup.py develop

View File

@ -38,26 +38,11 @@
# Matthew Gertner <matthew.gertner@gmail.com> # Matthew Gertner <matthew.gertner@gmail.com>
''' '''
Python API for Jenkins .. module:: jenkins
:platform: Unix, Windows
:synopsis: Python API to interact with Jenkins
Examples:: See examples at :doc:`example`
j = jenkins.Jenkins('http://your_url_here', 'username', 'password')
j.get_jobs()
j.create_job('empty', jenkins.EMPTY_CONFIG_XML)
j.disable_job('empty')
j.copy_job('empty', 'empty_copy')
j.enable_job('empty_copy')
j.reconfig_job('empty_copy', jenkins.RECONFIG_XML)
j.delete_job('empty')
j.delete_job('empty_copy')
# build a parameterized job
j.build_job('api-test', {
'param1': 'test value 1',
'param2': 'test value 2',
})
''' '''
#import sys #import sys
@ -152,6 +137,10 @@ class Jenkins(object):
''' '''
Create handle to Jenkins instance. Create handle to Jenkins instance.
All methods will raise :class:`JenkinsException` on failure.
:param username: Server username, ``str``
:param password: Server password, ``str``
:param url: URL of Jenkins server, ``str`` :param url: URL of Jenkins server, ``str``
''' '''
if url[-1] == '/': if url[-1] == '/':
@ -426,7 +415,9 @@ class Jenkins(object):
''' '''
Trigger build job. Trigger build job.
:param name: name of job
:param parameters: parameters for job, or ``None``, ``dict`` :param parameters: parameters for job, or ``None``, ``dict``
:param token: Jenkins API token
''' '''
if not self.job_exists(name): if not self.job_exists(name):
raise JenkinsException('no such job[%s]' % (name)) raise JenkinsException('no such job[%s]' % (name))