From af25ae6e07531422abee43150a535b4176bb9caa Mon Sep 17 00:00:00 2001 From: Doug Hellmann Date: Fri, 16 Feb 2018 15:24:12 -0500 Subject: [PATCH] remove sphinx-isms from README.rst and clean up docs The :doc: role is only known to Sphinx, so when we publish the README.rst to PyPI and include that role it causes the content to not render as proper HTML. This patch removes some of the content from the readme and moves it to the main index page for the documentation. It then removes the readme.rst file from the doc build because we don't need to include the same content multiple times. Change-Id: Ic46c7a9d8e91f01b5e6cef5d377a56856b586c70 Signed-off-by: Doug Hellmann --- README.rst | 36 ++++++------------------------------ doc/source/index.rst | 37 +++++++++++++++++++++++++++++-------- doc/source/readme.rst | 1 - 3 files changed, 35 insertions(+), 39 deletions(-) delete mode 100644 doc/source/readme.rst diff --git a/README.rst b/README.rst index 5d5c2d1..fff92d7 100644 --- a/README.rst +++ b/README.rst @@ -4,19 +4,6 @@ python-storyboardclient Python Client library for StoryBoard -* Free software: Apache license -* Documentation: http://docs.openstack.org/infra/storyboard/ -* Source: http://git.openstack.org/cgit/openstack-infra/python-storyboardclient -* Bugs: https://storyboard.openstack.org/#!/project/755 - -Features --------- - -* TODO - -Notes ------ - This is the StoryBoard python client! It lets you interact with StoryBoard from the comfort of your own terminal! There is no command to run this; instead you can import it into scripts. This @@ -24,22 +11,11 @@ lets you perform complex actions on things in StoryBoard, eg: add an helpful comment on all stories with 'cannot store contact information' in the description, pointing users at the relevant docs, but only if there is no comment to this effect already. (There is an example -of such a script in :doc:`usage`) - -Some sample commands are given in usage.rst. In general, most -resources (ie: stories, tasks, projects, and so on) -have a ``get_all()`` and ``get()`` method. The latter takes -the resource's id as a parameter, thought it can also take -other attributes (eg: tag name). - -To create a new resource, use the ``create()`` method. The -necessary parameters depend on the resource, and if not -documented, can be worked out from the relevant .py -file in the code for the StoryBoard API. - -The ``update()`` method will update mutable fields of the resource (again, -these vary depending on the resource). - -Finally, ``delete()`` will delete things. +of such a script in the documentation.) Happy task-tracking! + +* Free software: Apache license +* Documentation: http://docs.openstack.org/infra/storyboard/ +* Source: http://git.openstack.org/cgit/openstack-infra/python-storyboardclient +* Bugs: https://storyboard.openstack.org/#!/project/755 diff --git a/doc/source/index.rst b/doc/source/index.rst index af8b2e5..f4261bb 100644 --- a/doc/source/index.rst +++ b/doc/source/index.rst @@ -1,17 +1,39 @@ -.. python-storyboardclient 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. +========================= + python-storyboardclient +========================= -Welcome to python-storyboardclient's documentation! -=================================================== +This is the StoryBoard python client! It lets you interact with +StoryBoard from the comfort of your own terminal! There is no +command to run this; instead you can import it into scripts. This +lets you perform complex actions on things in StoryBoard, eg: add an +helpful comment on all stories with 'cannot store contact information' +in the description, pointing users at the relevant docs, but only +if there is no comment to this effect already. (There is an example +of such a script in :doc:`usage`) + +Some sample commands are given in :doc:`usage`. In general, most +resources (ie: stories, tasks, projects, and so on) +have a ``get_all()`` and ``get()`` method. The latter takes +the resource's id as a parameter, thought it can also take +other attributes (eg: tag name). + +To create a new resource, use the ``create()`` method. The +necessary parameters depend on the resource, and if not +documented, can be worked out from the relevant .py +file in the code for the StoryBoard API. + +The ``update()`` method will update mutable fields of the resource (again, +these vary depending on the resource). + +Finally, ``delete()`` will delete things. + +Happy task-tracking! Contents: .. toctree:: :maxdepth: 2 - readme installation usage contributing @@ -21,4 +43,3 @@ Indices and tables * :ref:`genindex` * :ref:`search` - diff --git a/doc/source/readme.rst b/doc/source/readme.rst deleted file mode 100644 index a6210d3..0000000 --- a/doc/source/readme.rst +++ /dev/null @@ -1 +0,0 @@ -.. include:: ../../README.rst