From 9f0f114b27a885045c8cd1a9ab23a4d3b2ddb546 Mon Sep 17 00:00:00 2001 From: Joshua Harlow Date: Mon, 2 Feb 2015 11:48:13 -0800 Subject: [PATCH] Fix up the docs into reasonable shape Make the docs include the exposed API's and be formatted better so that they are useful to users of debtcollector instead of not being useful. Change-Id: I6b1bdda206927d1475cabb1872a3fe21a178b125 --- README.rst | 5 ++--- doc/source/api.rst | 23 +++++++++++++++++++++++ doc/source/conf.py | 17 +++++++++++++---- doc/source/contributing.rst | 3 ++- doc/source/index.rst | 22 +++++++++++++--------- doc/source/installation.rst | 2 +- doc/source/readme.rst | 1 - doc/source/usage.rst | 7 ------- 8 files changed, 54 insertions(+), 26 deletions(-) create mode 100644 doc/source/api.rst delete mode 100644 doc/source/readme.rst delete mode 100644 doc/source/usage.rst diff --git a/README.rst b/README.rst index 0760cc3..e5b246d 100644 --- a/README.rst +++ b/README.rst @@ -1,6 +1,5 @@ -=============================== -debtcollector -=============================== +Debtcollector +============= A collection of python patterns that help you collect your technical debt in a non-destructive manner (following deprecation patterns and strategies and diff --git a/doc/source/api.rst b/doc/source/api.rst new file mode 100644 index 0000000..6683cc1 --- /dev/null +++ b/doc/source/api.rst @@ -0,0 +1,23 @@ +=== +API +=== + + +The currently documented publicly exposed API's for usage in your project +are defined below. + +.. warning:: + + External usage of internal utility functions and modules should be kept + to a **minimum** as they may be altered, refactored or moved to other + locations **without** notice (and without the typical deprecation cycle). + +Moves +----- + +.. automodule:: debtcollector.moves + +Renames +------- + +.. automodule:: debtcollector.renames diff --git a/doc/source/conf.py b/doc/source/conf.py index 70f9ec5..0c18ec9 100644 --- a/doc/source/conf.py +++ b/doc/source/conf.py @@ -12,6 +12,7 @@ # See the License for the specific language governing permissions and # limitations under the License. +import datetime import os import sys @@ -22,8 +23,8 @@ sys.path.insert(0, os.path.abspath('../..')) # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom ones. extensions = [ 'sphinx.ext.autodoc', - #'sphinx.ext.intersphinx', - 'oslosphinx' + 'sphinx.ext.viewcode', + 'oslosphinx', ] # autodoc generation is a bit aggressive and a nuisance when doing heavy @@ -38,7 +39,7 @@ master_doc = 'index' # General information about the project. project = u'debtcollector' -copyright = u'2013, OpenStack Foundation' +copyright = u'%s, OpenStack Foundation' % datetime.date.today().year # If true, '()' will be appended to :func: etc. cross-reference text. add_function_parentheses = True @@ -72,4 +73,12 @@ latex_documents = [ ] # Example configuration for intersphinx: refer to the Python standard library. -#intersphinx_mapping = {'http://docs.python.org/': None} \ No newline at end of file +#intersphinx_mapping = {'http://docs.python.org/': None} + +# -- Options for autoddoc ---------------------------------------------------- + +# Keep source order +autodoc_member_order = 'bysource' + +# Always include members +autodoc_default_flags = ['members', 'show-inheritance'] diff --git a/doc/source/contributing.rst b/doc/source/contributing.rst index ed77c12..1f5ca23 100644 --- a/doc/source/contributing.rst +++ b/doc/source/contributing.rst @@ -1,4 +1,5 @@ ============ Contributing ============ -.. include:: ../../CONTRIBUTING.rst \ No newline at end of file + +.. include:: ../../CONTRIBUTING.rst diff --git a/doc/source/index.rst b/doc/source/index.rst index e578a14..947d0e1 100644 --- a/doc/source/index.rst +++ b/doc/source/index.rst @@ -1,19 +1,23 @@ -.. debtcollector documentation master file, created by - sphinx-quickstart on Tue Jul 9 22:26:36 2013. - You can adapt this file completely to your liking, but it should at least - contain the root `toctree` directive. - Welcome to debtcollector's documentation! -======================================================== +========================================= -Contents: +.. include:: ../../README.rst + +.. note:: + + It should be noted that even though it is designed with OpenStack + integration in mind, and that is where most of its *current* + integration is it aims to be generally usable and useful in any + project. + +Contents +-------- .. toctree:: :maxdepth: 2 - readme installation - usage + api contributing Indices and tables diff --git a/doc/source/installation.rst b/doc/source/installation.rst index 9cccbe3..46fec3e 100644 --- a/doc/source/installation.rst +++ b/doc/source/installation.rst @@ -9,4 +9,4 @@ At the command line:: Or, if you have virtualenvwrapper installed:: $ mkvirtualenv debtcollector - $ pip install debtcollector \ No newline at end of file + $ pip install debtcollector diff --git a/doc/source/readme.rst b/doc/source/readme.rst deleted file mode 100644 index 38ba804..0000000 --- a/doc/source/readme.rst +++ /dev/null @@ -1 +0,0 @@ -.. include:: ../../README.rst \ No newline at end of file diff --git a/doc/source/usage.rst b/doc/source/usage.rst deleted file mode 100644 index 3460a65..0000000 --- a/doc/source/usage.rst +++ /dev/null @@ -1,7 +0,0 @@ -======== -Usage -======== - -To use debtcollector in a project:: - - import debtcollector \ No newline at end of file