diff --git a/doc/Makefile b/doc/Makefile index 5d450d1..336b94d 100644 --- a/doc/Makefile +++ b/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 ' where 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 diff --git a/doc/index.rst b/doc/index.rst deleted file mode 100644 index 4536dea..0000000 --- a/doc/index.rst +++ /dev/null @@ -1,217 +0,0 @@ -Welcome to Python Jenkins's documentation! -========================================== - -Python Jenkins is a library for the remote API of the `Jenkins -`_ 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` - diff --git a/doc/source/api.rst b/doc/source/api.rst new file mode 100644 index 0000000..b950f39 --- /dev/null +++ b/doc/source/api.rst @@ -0,0 +1,8 @@ +:title: API reference + +API reference +============= + +.. automodule:: jenkins + :members: + :undoc-members: diff --git a/doc/conf.py b/doc/source/conf.py similarity index 96% rename from doc/conf.py rename to doc/source/conf.py index a39a6a4..35f9bb6 100644 --- a/doc/conf.py +++ b/doc/source/conf.py @@ -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. diff --git a/doc/source/example.rst b/doc/source/example.rst new file mode 100644 index 0000000..54fbda6 --- /dev/null +++ b/doc/source/example.rst @@ -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. diff --git a/doc/source/index.rst b/doc/source/index.rst new file mode 100644 index 0000000..23a5030 --- /dev/null +++ b/doc/source/index.rst @@ -0,0 +1,23 @@ +Welcome to Python Jenkins's documentation! +========================================== + +Python Jenkins is a library for the remote API of the `Jenkins +`_ 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` diff --git a/doc/source/install.rst b/doc/source/install.rst new file mode 100644 index 0000000..2312fa4 --- /dev/null +++ b/doc/source/install.rst @@ -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 diff --git a/jenkins/__init__.py b/jenkins/__init__.py index bcea746..f0fe0ce 100644 --- a/jenkins/__init__.py +++ b/jenkins/__init__.py @@ -38,26 +38,11 @@ # Matthew Gertner ''' -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))