Update docs (#627)

Co-authored-by: Oliver Ruebel <[email protected]>
hdmf-dev · Jun 9, 2021 · 36db0e8 · 36db0e8
1 parent 1b084d5
commit 36db0e8
Show file tree

Hide file tree

Showing 11 changed files with 238 additions and 167 deletions.
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -1,5 +1,10 @@
 # HDMF Changelog
 
+## HDMF 2.5.8 (Upcoming)
+
+### Minor improvements
+- Improve Sphinx documentation. @rly (#627)
+
 ## HDMF 2.5.7 (June 4, 2021)
 
 ### Bug fix

diff --git a/docs/CONTRIBUTING.rst b/docs/CONTRIBUTING.rst
@@ -1,5 +1,5 @@
-How to contribute to HDMF software and documents
-=================================================
+Contributing Guide
+==================
 
 .. _sec-code-of-conduct:
 
@@ -87,32 +87,41 @@ From your local copy directory, use the following commands.
 Styleguides
 -----------
 
+Python Code Styleguide
+^^^^^^^^^^^^^^^^^^^^^^
+
+Before you create a Pull Request, make sure you are following the HDMF style guide (PEP8_).
+To check whether your code conforms to the HDMF style guide, simply run the flake8_ tool in the project's root
+directory.
+
+.. _flake8: http://flake8.pycqa.org/en/latest/
+.. _PEP8: https://www.python.org/dev/peps/pep-0008/
+
+.. code::
+
+   $ flake8
+
 Git Commit Message Styleguide
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 * Use the present tense ("Add feature" not "Added feature")
 * The first should be short and descriptive.
 * Additional details may be included in further paragraphs.
-* If a commit fixes an issues, then include "Fix #X" where X is the number of the issue.
+* If a commit fixes an issue, then include "Fix #X" where X is the number of the issue.
 * Reference relevant issues and pull requests liberally after the first line.
 
 Documentation Styleguide
 ^^^^^^^^^^^^^^^^^^^^^^^^
 
 All documentations is written in reStructuredText (RST) using Sphinx.
 
-Python Code Styleguide
-^^^^^^^^^^^^^^^^^^^^^^
-
-Python coding style is checked via ``flake8`` for automatic checking of PEP8 style during pull requests.
-
 Endorsement
 -----------
 
 Please do not take working with an organization (e.g., during a hackathon or via GitHub) as an endorsement of your work or your organization. It's okay to say e.g., “We worked with XXXXX to advance science” but not e.g., “XXXXX supports our work on HDMF”.”
 
 License and Copyright
-=======================
+---------------------
 
 See the `license <https://raw.githubusercontent.com/hdmf-dev/hdmf/dev/license.txt>`_ files for details about the copyright and license.
 

diff --git a/docs/source/_static/theme_overrides.css b/docs/source/_static/theme_overrides.css
@@ -0,0 +1,7 @@
+.wy-side-nav-search .wy-dropdown>a.icon img.logo, .wy-side-nav-search>a.icon img.logo {
+  width: 150px;
+}
+
+.wy-nav-content {
+  max-width: 1000px !important;
+}
diff --git a/docs/source/building_api.rst b/docs/source/building_api.rst
@@ -1,4 +1,4 @@
-Building API classes
+Building API Classes
 ====================
 
 After you have written an extension, you will need a Pythonic way to interact with the data model. To do this,

diff --git a/docs/source/conf.py b/docs/source/conf.py
@@ -175,7 +175,7 @@
 # Add any paths that contain custom static files (such as style sheets) here,
 # relative to this directory. They are copied after the builtin static files,
 # so a file named "default.css" will overwrite the builtin "default.css".
-# html_static_path = ['_static']
+html_static_path = ['_static']
 
 # If not '', a 'Last updated on:' timestamp is inserted at every page bottom,
 # using the given strftime format.
@@ -325,5 +325,5 @@ def skip(app, what, name, obj, skip, options):
 
 def setup(app):
     app.connect('builder-inited', run_apidoc)
-    app.add_css_file("theme_overrides.css")  # overrides for wide tables in RTD theme
+    app.add_css_file("theme_overrides.css")
     app.connect("autodoc-skip-member", skip)
diff --git a/docs/source/extensions.rst b/docs/source/extensions.rst
@@ -1,6 +1,6 @@
 .. _extending-standard:
 
-Extending standards
+Extending Standards
 ===================
 
 The following page will discuss how to extend a standard using HDMF.

diff --git a/docs/source/getting_started.rst b/docs/source/getting_started.rst
diff --git a/docs/source/index.rst b/docs/source/index.rst
@@ -1,8 +1,3 @@
-.. HDMF documentation master file, created by
-   sphinx-quickstart on Thu Nov 17 10:41:07 2016.
-   You can adapt this file completely to your liking, but it should at least
-   contain the root `toctree` directive.
-
 The Hierarchical Data Modeling Framework
 ========================================
 
@@ -17,55 +12,60 @@ with the intention of providing it as an open-source tool for other scientific c
 
 If you use HDMF in your research, please use the following citation:
 
-A. J. Tritt et al., "HDMF: Hierarchical Data Modeling Framework for Modern Science Data Standards,"
-2019 IEEE International Conference on Big Data (Big Data), Los Angeles, CA, USA, 2019, pp. 165-179,
-doi: 10.1109/BigData47090.2019.9005648.
+    A. J. Tritt et al., "HDMF: Hierarchical Data Modeling Framework for Modern Science Data Standards,"
+    2019 IEEE International Conference on Big Data (Big Data), Los Angeles, CA, USA, 2019, pp. 165-179,
+    doi: 10.1109/BigData47090.2019.9005648.
 
 
 .. toctree::
+   :hidden:
    :maxdepth: 2
    :caption: Getting Started
 
-   getting_started
-   contributing
+   install_users
+   tutorials/index
 
 .. toctree::
+   :hidden:
    :maxdepth: 2
    :caption: Overview
 
    overview_intro
    overview_software_architecture
    overview_citing
 
+
 .. toctree::
+   :hidden:
    :maxdepth: 2
    :caption: Resources
 
-   tutorials/index
+   api_docs
    extensions
    building_api
-   validation
    export
-   api_docs
-   software_process
+   validation
+
+.. toctree::
+   :hidden:
+   :caption: For Developers
+
+   install_developers
+   contributing
    make_roundtrip_test
+   software_process
 
 .. toctree::
+   :hidden:
    :maxdepth: 2
    :caption: For Maintainers
 
    make_a_release
    update_requirements
 
 .. toctree::
+   :hidden:
    :maxdepth: 2
    :caption: Legal
 
    legal
-
-Indices and tables
-==================
-
-* :ref:`genindex`
-* :ref:`modindex`
-* :ref:`search`