From 788c70ab26ec4ca3fe6aaa842c0468fafcb01c1f Mon Sep 17 00:00:00 2001 From: Thomas Bechtold Date: Mon, 7 Dec 2015 08:08:55 +0100 Subject: [PATCH] Restructure documentation - Convert README from markdown to restructured text - Add documentation template for Sphinx - Add setup.cfg file so that sphinx build is done in doc/build/html as expected by infra scripts. This is the way OpenStack projects usually do documentation. Change-Id: I7e40a2e6fe14e63bd33f9b1ea1f31db23c7501b8 --- MANIFEST.in | 2 +- README.rst | 35 +++++++++++++++++ doc/source/conf.py | 65 +++++++++++++++++++++++++++++++ README.md => doc/source/index.rst | 64 +++++++++++++++++++----------- doc/source/static/.placeholder | 0 setup.cfg | 5 +++ setup.py | 2 +- test-requirements.txt | 3 ++ tox.ini | 3 ++ 9 files changed, 155 insertions(+), 24 deletions(-) create mode 100644 README.rst create mode 100644 doc/source/conf.py rename README.md => doc/source/index.rst (50%) create mode 100644 doc/source/static/.placeholder create mode 100644 setup.cfg diff --git a/MANIFEST.in b/MANIFEST.in index 04f196a..a5021c6 100644 --- a/MANIFEST.in +++ b/MANIFEST.in @@ -1,2 +1,2 @@ -include README.md +include README.rst include LICENSE diff --git a/README.rst b/README.rst new file mode 100644 index 0000000..b692030 --- /dev/null +++ b/README.rst @@ -0,0 +1,35 @@ +pymod2pkg +========= + +`pymod2pkg` is a simple python module for translating python module names to +corresponding package names which is a common problem in the packaging world. +It is used for the OpenStack rpm packaging initiative. +For more information about the OpenStack rpm packaging initiative, please +follow the link to the wiki page: + + https://wiki.openstack.org/wiki/Rpm-packaging + +In the unfortunate event that bugs are discovered, they should +be reported to the appropriate bug tracker. If you obtained +the software from a 3rd party operating system vendor, it is +often wise to use their own bug tracker for reporting problems. +In all other cases use the master OpenStack bug tracker, +available at: + + https://bugs.launchpad.net/pymod2pkg + +Developers wishing to work on pymod2pkg should always base +their work on the latest code, available from the master GIT +repository at: + + https://git.openstack.org/cgit/openstack/pymod2pkg + +Developers should also join the discussion on the mailing list, +at: + + http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev + +or join the IRC channel on + + http://webchat.freenode.net/?channels=openstack-rpm-packaging + diff --git a/doc/source/conf.py b/doc/source/conf.py new file mode 100644 index 0000000..6f6bfd0 --- /dev/null +++ b/doc/source/conf.py @@ -0,0 +1,65 @@ +# -*- coding: utf-8 -*- + +import os +import sys + +sys.path.insert(0, os.path.abspath('../..')) +# -- General configuration ---------------------------------------------------- + +# Add any Sphinx extension module names here, as strings. They can be +# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom ones. +extensions = [ + 'sphinx.ext.autodoc', + 'oslosphinx', +] + +# autodoc generation is a bit aggressive and a nuisance when doing heavy +# text edit cycles. +# execute "export SPHINX_DEBUG=1" in your terminal to disable + +# Add any paths that contain templates here, relative to this directory. +# templates_path = [] + +# The suffix of source filenames. +source_suffix = '.rst' + +# The master toctree document. +master_doc = 'index' + +# General information about the project. +project = u'pymod2pkg' +copyright = u'2016, OpenStack Foundation' + +# If true, '()' will be appended to :func: etc. cross-reference text. +add_function_parentheses = True + +# If true, the current module name will be prepended to all description +# unit titles (such as .. function::). +add_module_names = True + +# The name of the Pygments (syntax highlighting) style to use. +pygments_style = 'sphinx' + +# -- Options for HTML output -------------------------------------------------- + +# The theme to use for HTML and HTML Help pages. Major themes that come with +# Sphinx are currently 'default' and 'sphinxdoc'. +# html_theme_path = ["."] +# html_theme = '_theme' +html_static_path = ['static'] + +# Output file base name for HTML help builder. +htmlhelp_basename = '%sdoc' % project + +git_cmd = "git log --pretty=format:'%ad, commit %h' --date=local -n1" +html_last_updated_fmt = os.popen(git_cmd).read() + +# Grouping the document tree into LaTeX files. List of tuples +# (source start file, target name, title, author, documentclass +# [howto/manual]). +latex_documents = [ + ('index', + '%s.tex' % project, + '%s Documentation' % project, + 'OpenStack Foundation', 'manual'), +] diff --git a/README.md b/doc/source/index.rst similarity index 50% rename from README.md rename to doc/source/index.rst index 6e93ba9..2291748 100644 --- a/README.md +++ b/doc/source/index.rst @@ -1,60 +1,80 @@ -#: pymod2pkg +pymod2pkg +========= `pymod2pkg` is a simple python module for translating python module names to corresponding package names which is a common problem in the packaging world. -Note that [rdopkg](https://github.com/redhat-openstack/rdopkg) uses this -module to check whether packages corresponding to `requirements.txt` are -available across distros and more. +.. note:: Note that rdopkg_ uses this module to check whether packages + corresponding to `requirements.txt` are available across distros + and more. +.. _rdopkg: https://github.com/redhat-openstack/rdopkg -## Installation +Installation +============ - -### from source +From source +*********** If you want to hack `pymod2pkg` or just have the latest version without waiting for next release, I suggest using the git repo directly a la - git clone https://github.com/openstack/pymod2pkg - cd pymod2pkg - python setup.py develop --user +.. code-block:: shell + + git clone https://git.openstack.org/openstack/pymod2pkg + cd pymod2pkg + python setup.py develop --user -### from PyPI +From PyPI +********* For your convenience, `pymod2pkg` is also available from the Cheese Shop: - pip install pymod2pkg +.. code-block:: shell + pip install pymod2pkg - -## Usage +Usage +===== `module2package` is probably all you need, it accepts a module name to convert and a linux distribution name as returned by `platform.linux_distribution()[0]`: - import pymod2pkg - - pkg = pymod2pkg.module2package('six', 'Fedora') +.. code-block:: python + + import pymod2pkg + pkg = pymod2pkg.module2package('six', 'Fedora') There's not much more, really, so RTFS. - - -## Fixing/extending the map +Fixing/extending the map +======================== Currently, only package maps for RPM-based systems are provided, but it'd be nice to have all the distros covered and it's really easy to do. See `*_PKG_MAP` and `get_pkg_map`, hack it to your liking and submit review by - git review +.. code-block:: shell + + git review -## Running the testsuite +Running the testsuite +===================== Run tests by: +.. code-block:: shell + python tests.py + + +Indices and tables +================== + +* :ref:`genindex` +* :ref:`search` + diff --git a/doc/source/static/.placeholder b/doc/source/static/.placeholder new file mode 100644 index 0000000..e69de29 diff --git a/setup.cfg b/setup.cfg new file mode 100644 index 0000000..8098c73 --- /dev/null +++ b/setup.cfg @@ -0,0 +1,5 @@ +[build_sphinx] +source-dir = doc/source +build-dir = doc/build +all_files = 1 + diff --git a/setup.py b/setup.py index 13c4701..8ca1978 100644 --- a/setup.py +++ b/setup.py @@ -16,7 +16,7 @@ pymod2pkg_classifiers = [ "Topic :: Utilities", ] -with open("README.md", "r") as fp: +with open("README.rst", "r") as fp: pymod2pkg_long_description = fp.read() setup(name="pymod2pkg", diff --git a/test-requirements.txt b/test-requirements.txt index b891cfc..13057b8 100644 --- a/test-requirements.txt +++ b/test-requirements.txt @@ -2,3 +2,6 @@ flake8 testrepository>=0.0.18 testresources>=0.2.4 testtools>=1.4.0 + +sphinx!=1.2.0,!=1.3b1,<1.3,>=1.1.2 +oslosphinx!=3.4.0,>=2.5.0 # Apache-2.0 diff --git a/tox.ini b/tox.ini index 29d1e93..13b2241 100644 --- a/tox.ini +++ b/tox.ini @@ -22,3 +22,6 @@ commands = flake8 [testenv:venv] commands = {posargs} +[testenv:docs] +commands = python setup.py build_sphinx +