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

@@ -1,2 +1,2 @@
-include README.md
+include README.rst
 include LICENSE

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
+

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'),
+]

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
+.. note:: Note that rdopkg_ uses this module to check whether packages
-module to check whether packages corresponding to `requirements.txt` are
+          corresponding to `requirements.txt` are available across distros
-available across distros and more.
+          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
+.. 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:
 
+.. 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
+.. 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
 
+.. 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`
+

setup.cfg

@@ -0,0 +1,5 @@
+[build_sphinx]
+source-dir = doc/source
+build-dir  = doc/build
+all_files  = 1
+

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",

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

tox.ini

@@ -22,3 +22,6 @@ commands = flake8
 [testenv:venv]
 commands = {posargs}
 
+[testenv:docs]
+commands = python setup.py build_sphinx
+