opendev/python-storyboardclient
Code Issues Proposed changes

remove sphinx-isms from README.rst and clean up docs

Browse Source 
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 <doug@doughellmann.com>
This commit is contained in:
Doug Hellmann 2018-02-16 15:24:12 -05:00
parent e8b3de622c
commit af25ae6e07
3 changed files with 35 additions and 39 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

36
README.rst
View File

@ -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

37
doc/source/index.rst
View File

@ -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`

1
doc/source/readme.rst
View File

@ -1 +0,0 @@
.. include:: ../../README.rst