First pass at docs restructure

Author: coretl

CONTRIBUTING.rst

@@ -0,0 +1,72 @@
+Contributing
+============
+
+Contributions and issues are most welcome! All issues and pull requests are
+handled through github on the `dls_controls repository`_. Also, please check for
+any existing issues before filing a new one. If you have a great idea but it
+involves big changes, please file a ticket before making a pull request! We
+want to make sure you don't spend your time coding something that might not fit
+the scope of the project.
+
+.. _dls_controls repository: https://github.com/dls-controls/pythonIoc/issues
+
+Running the tests
+-----------------
+
+To get the source source code and run the unit tests, run::
+
+    $ git clone git://github.com/dls-controls/pythonIoc.git
+    $ cd pythonIoc
+    $ pipenv install --dev
+    $ pipenv run tests
+
+While 100% code coverage does not make a library bug-free, it significantly
+reduces the number of easily caught bugs! Please make sure coverage remains the
+same or is improved by a pull request!
+
+Code Styling
+------------
+
+The code in this repository conforms to standards set by the following tools:
+
+- flake8_ for style checks
+
+.. _flake8: http://flake8.pycqa.org/en/latest/
+
+These tests will be run on code when running ``pipenv run tests`` and also
+automatically at check in. Please read the tool documentation for details
+on how to fix the errors it reports.
+
+Documentation
+-------------
+
+Documentation is contained in the ``docs`` directory and extracted from
+docstrings of the API.
+
+Docs follow the underlining convention::
+
+    Headling 1 (page title)
+    =======================
+
+    Heading 2
+    ---------
+
+    Heading 3
+    ~~~~~~~~~
+
+
+You can build the docs from the project directory by running::
+
+    $ pipenv run docs
+    $ firefox build/html/index.html
+
+
+Release Checklist
+-----------------
+
+Before a new release, please go through the following checklist:
+
+- Choose a new PEP440 compliant release number
+- Git tag the version with a message summarizing the changes
+- Push to github and the actions will make a release on pypi
+- Push to internal gitlab and do a dls-release.py of the tag

docs/_static/theme_overrides.css

@@ -1,4 +1,33 @@
+/* override table width restrictions */
+@media screen and (min-width: 639px) {
+    .wy-table-responsive table td {
+        /* !important prevents the common CSS stylesheets from
+           overriding this as on RTD they are loaded after this stylesheet */
+        white-space: normal !important;
+    }
+}
+
+/* override table padding */
+.rst-content table.docutils th, .rst-content table.docutils td {
+    padding: 4px 6px;
+}
+
 /* allow us to stop margin after list so we can add to it */
 .no-margin-after-ul ul {
     margin-bottom: 0 !important;
 }
+
+/* Add two-column option */
+@media only screen and (min-width: 1000px),
+       only screen and (min-width: 500px) and (max-width: 768px){
+    .columns {
+        padding-left: 5px;
+        padding-right: 5px;
+        float: left;
+        width: 50%;
+    }
+}
+
+.endcolumns {
+    clear: both
+}

docs/conf.py

@@ -22,8 +22,9 @@
 import softioc  # noqa
 
 # General information about the project.
-project = u'Python Soft IOC'
-copyright = u'2011, Michael Abbott'
+project = u'pythonIoc'
+copyright = u'2008, Diamond Light Source'
+author = 'Michael Abbott'
 
 # The full version, including alpha/beta/rc tags.
 release = softioc.__version__
@@ -40,6 +41,10 @@
 # Add any Sphinx extension module names here, as strings. They can be extensions
 # coming with Sphinx (named 'sphinx.ext.*') or your custom ones.
 extensions = [
+    # Use this for generating API docs
+    'sphinx.ext.autodoc',
+    # This can parse google style docstrings
+    'sphinx.ext.napoleon',
     # For linking to external sphinx documentation
     'sphinx.ext.intersphinx',
     # Add links to source code in API docs
@@ -48,8 +53,6 @@
     'sphinx_multiversion',
 ]
 
-viewcode_import = True
-
 # If true, Sphinx will warn about all references where the target cannot
 # be found.
 nitpicky = True
@@ -60,6 +63,20 @@
 # ('envvar', 'LD_LIBRARY_PATH').
 nitpick_ignore = [('py:func', 'int')]
 
+# Both the class’ and the __init__ method’s docstring are concatenated and
+# inserted into the main body of the autoclass directive
+autoclass_content = 'both'
+
+# Order the members by the order they appear in the source code
+autodoc_member_order = 'bysource'
+
+# Don't inherit docstrings from baseclasses
+autodoc_inherit_docstrings = False
+
+# The name of a reST role (builtin or Sphinx extension) to use as the default
+# role, that is, for text marked up `like this`
+default_role = 'any'
+
 # Add any paths that contain templates here, relative to this directory.
 templates_path = ['_templates']
 

docs/explanations/use-cases.rst

@@ -0,0 +1,4 @@
+Use Cases
+=========
+
+Write about what it is good for

docs/how-to/use-asyncio-in-an-ioc.rst

@@ -0,0 +1,4 @@
+Use `asyncio` in an IOC
+=======================
+
+Write about the differences creating an IOC using `AsyncioDispatcher`

docs/index.rst

@@ -1,19 +1,74 @@
-.. _index:
-
 .. include:: ../README.rst
     :end-before: when included in index.rst
 
+How the documentation is structured
+-----------------------------------
+
+.. rst-class:: columns
+
+:ref:`tutorials`
+~~~~~~~~~~~~~~~~
+
+Tutorials for installation, library and commandline usage. New users start here.
+
+.. rst-class:: columns
+
+:ref:`how-to`
+~~~~~~~~~~~~~
+
+Practical step-by-step guides for the more experienced user.
+
+.. rst-class:: columns
+
+:ref:`explanations`
+~~~~~~~~~~~~~~~~~~~
+
+Explanation of how the library works and why it works that way.
+
+.. rst-class:: columns
+
+:ref:`reference`
+~~~~~~~~~~~~~~~~
+
+Technical reference material, for classes, methods, APIs, commands, and contributing to the project.
+
+.. rst-class:: endcolumns
+
+About the documentation
+~~~~~~~~~~~~~~~~~~~~~~~
+
+`Why is the documentation structured this way? <https://documentation.divio.com>`_
+
+.. toctree::
+    :caption: Tutorials
+    :name: tutorials
+    :maxdepth: 1
+
+    tutorials/installation
+    tutorials/creating-an-ioc
+
+.. toctree::
+    :caption: How-to Guides
+    :name: how-to
+    :maxdepth: 1
+
+    how-to/use-asyncio-in-an-ioc
+
+.. toctree::
+    :caption: Explanations
+    :name: explanations
+    :maxdepth: 1
+
+    explanations/use-cases
+
 .. rst-class:: no-margin-after-ul
 
-..  toctree::
-    :numbered:
-    :maxdepth: 2
+.. toctree::
+    :caption: Reference
+    :name: reference
+    :maxdepth: 1
 
-    pythonsoftioc
-    records
-    softioc
+    reference/api
+    reference/contributing
 
 * :ref:`genindex`
-* :ref:`modindex`
-* :ref:`search`
-* `Selected source code <_modules/index.html>`_