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
parent
c3e23c2973
commit
170e878d2a
31
doc/Makefile
31
doc/Makefile
@ -5,14 +5,16 @@
|
||||
SPHINXOPTS =
|
||||
SPHINXBUILD = sphinx-build
|
||||
PAPER =
|
||||
BUILDDIR = _build
|
||||
BUILDDIR = build
|
||||
|
||||
# Internal variables.
|
||||
PAPEROPT_a4 = -D latex_paper_size=a4
|
||||
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:
|
||||
@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 " text to make text files"
|
||||
@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 " linkcheck to check all external links for integrity"
|
||||
@echo " doctest to run all doctests embedded in the documentation (if enabled)"
|
||||
@ -100,7 +105,7 @@ latex:
|
||||
latexpdf:
|
||||
$(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex
|
||||
@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."
|
||||
|
||||
text:
|
||||
@ -113,6 +118,24 @@ man:
|
||||
@echo
|
||||
@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:
|
||||
$(SPHINXBUILD) -b changes $(ALLSPHINXOPTS) $(BUILDDIR)/changes
|
||||
@echo
|
||||
|
||||
217
doc/index.rst
217
doc/index.rst
@ -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
8
doc/source/api.rst
Normal file
@ -0,0 +1,8 @@
|
||||
:title: API reference
|
||||
|
||||
API reference
|
||||
=============
|
||||
|
||||
.. automodule:: jenkins
|
||||
:members:
|
||||
:undoc-members:
|
||||
@ -15,12 +15,12 @@
|
||||
import os
|
||||
import sys
|
||||
|
||||
sys.path.insert(0, os.path.abspath('..'))
|
||||
|
||||
# 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
|
||||
# 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('../../jenkins'))
|
||||
|
||||
# -- 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 = ['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.
|
||||
templates_path = ['_templates']
|
||||
|
||||
@ -124,7 +130,7 @@ html_theme = 'default'
|
||||
# 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,
|
||||
# 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,
|
||||
# using the given strftime format.
|
||||
22
doc/source/example.rst
Normal file
22
doc/source/example.rst
Normal 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
23
doc/source/index.rst
Normal 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
24
doc/source/install.rst
Normal 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
|
||||
@ -38,26 +38,11 @@
|
||||
# Matthew Gertner <matthew.gertner@gmail.com>
|
||||
|
||||
'''
|
||||
Python API for Jenkins
|
||||
.. module:: jenkins
|
||||
:platform: Unix, Windows
|
||||
:synopsis: Python API to interact with Jenkins
|
||||
|
||||
Examples::
|
||||
|
||||
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',
|
||||
})
|
||||
See examples at :doc:`example`
|
||||
'''
|
||||
|
||||
#import sys
|
||||
@ -152,6 +137,10 @@ class Jenkins(object):
|
||||
'''
|
||||
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``
|
||||
'''
|
||||
if url[-1] == '/':
|
||||
@ -426,7 +415,9 @@ class Jenkins(object):
|
||||
'''
|
||||
Trigger build job.
|
||||
|
||||
:param name: name of job
|
||||
:param parameters: parameters for job, or ``None``, ``dict``
|
||||
:param token: Jenkins API token
|
||||
'''
|
||||
if not self.job_exists(name):
|
||||
raise JenkinsException('no such job[%s]' % (name))
|
||||
|
||||
Loading…
Reference in New Issue
Block a user