From 29bf6233fb8822bf63b7c21695af6378b8b5c360 Mon Sep 17 00:00:00 2001 From: Dan Lipsitt Date: Sun, 20 Aug 2017 15:24:12 -0700 Subject: [PATCH 1/7] Init sphinx docs with sphinx-quickstart. ``` sphinx-quickstart --sep --project=OpenHTF --author="OpenHTF Contributors" \ --language=en --ext-viewcode --ext-autodoc --makefile --batchfile --suffix=.rst \ --master=index docs ``` --- docs/source/conf.py | 172 ++++++++++++++++++++++++++++++++++++++++++ docs/source/index.rst | 20 +++++ 2 files changed, 192 insertions(+) create mode 100644 docs/source/conf.py create mode 100644 docs/source/index.rst diff --git a/docs/source/conf.py b/docs/source/conf.py new file mode 100644 index 000000000..73682ed5b --- /dev/null +++ b/docs/source/conf.py @@ -0,0 +1,172 @@ +# -*- coding: utf-8 -*- +# +# OpenHTF documentation build configuration file, created by +# sphinx-quickstart on Sun Aug 20 15:23:48 2017. +# +# This file is execfile()d with the current directory set to its +# containing dir. +# +# Note that not all possible configuration values are present in this +# autogenerated file. +# +# All configuration values have a default; values that are commented out +# serve to show the default. + +# If extensions (or modules to document with autodoc) are in another directory, +# add these directories to sys.path here. If the directory is relative to the +# documentation root, use os.path.abspath to make it absolute, like shown here. +# +# import os +# import sys +# sys.path.insert(0, os.path.abspath('.')) + + +# -- General configuration ------------------------------------------------ + +# If your documentation needs a minimal Sphinx version, state it here. +# +# needs_sphinx = '1.0' + +# Add any Sphinx extension module names here, as strings. They can be +# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom +# ones. +extensions = ['sphinx.ext.autodoc', + 'sphinx.ext.viewcode'] + +# Add any paths that contain templates here, relative to this directory. +templates_path = ['_templates'] + +# The suffix(es) of source filenames. +# You can specify multiple suffix as a list of string: +# +# source_suffix = ['.rst', '.md'] +source_suffix = '.rst' + +# The master toctree document. +master_doc = 'index' + +# General information about the project. +project = u'OpenHTF' +copyright = u'2017, OpenHTF Contributors' +author = u'OpenHTF Contributors' + +# The version info for the project you're documenting, acts as replacement for +# |version| and |release|, also used in various other places throughout the +# built documents. +# +# The short X.Y version. +version = u'' +# The full version, including alpha/beta/rc tags. +release = u'' + +# The language for content autogenerated by Sphinx. Refer to documentation +# for a list of supported languages. +# +# This is also used if you do content translation via gettext catalogs. +# Usually you set "language" from the command line for these cases. +language = 'en' + +# List of patterns, relative to source directory, that match files and +# directories to ignore when looking for source files. +# This patterns also effect to html_static_path and html_extra_path +exclude_patterns = [] + +# The name of the Pygments (syntax highlighting) style to use. +pygments_style = 'sphinx' + +# If true, `todo` and `todoList` produce output, else they produce nothing. +todo_include_todos = False + + +# -- Options for HTML output ---------------------------------------------- + +# The theme to use for HTML and HTML Help pages. See the documentation for +# a list of builtin themes. +# +html_theme = 'alabaster' + +# Theme options are theme-specific and customize the look and feel of a theme +# further. For a list of options available for each theme, see the +# documentation. +# +# html_theme_options = {} + +# 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'] + +# Custom sidebar templates, must be a dictionary that maps document names +# to template names. +# +# This is required for the alabaster theme +# refs: http://alabaster.readthedocs.io/en/latest/installation.html#sidebars +html_sidebars = { + '**': [ + 'about.html', + 'navigation.html', + 'relations.html', # needs 'show_related': True theme option to display + 'searchbox.html', + 'donate.html', + ] +} + + +# -- Options for HTMLHelp output ------------------------------------------ + +# Output file base name for HTML help builder. +htmlhelp_basename = 'OpenHTFdoc' + + +# -- Options for LaTeX output --------------------------------------------- + +latex_elements = { + # The paper size ('letterpaper' or 'a4paper'). + # + # 'papersize': 'letterpaper', + + # The font size ('10pt', '11pt' or '12pt'). + # + # 'pointsize': '10pt', + + # Additional stuff for the LaTeX preamble. + # + # 'preamble': '', + + # Latex figure (float) alignment + # + # 'figure_align': 'htbp', +} + +# Grouping the document tree into LaTeX files. List of tuples +# (source start file, target name, title, +# author, documentclass [howto, manual, or own class]). +latex_documents = [ + (master_doc, 'OpenHTF.tex', u'OpenHTF Documentation', + u'OpenHTF Contributors', 'manual'), +] + + +# -- Options for manual page output --------------------------------------- + +# One entry per manual page. List of tuples +# (source start file, name, description, authors, manual section). +man_pages = [ + (master_doc, 'openhtf', u'OpenHTF Documentation', + [author], 1) +] + + +# -- Options for Texinfo output ------------------------------------------- + +# Grouping the document tree into Texinfo files. List of tuples +# (source start file, target name, title, author, +# dir menu entry, description, category) +texinfo_documents = [ + (master_doc, 'OpenHTF', u'OpenHTF Documentation', + author, 'OpenHTF', 'One line description of project.', + 'Miscellaneous'), +] + + + diff --git a/docs/source/index.rst b/docs/source/index.rst new file mode 100644 index 000000000..7197e3bf1 --- /dev/null +++ b/docs/source/index.rst @@ -0,0 +1,20 @@ +.. OpenHTF documentation master file, created by + sphinx-quickstart on Sun Aug 20 15:23:48 2017. + You can adapt this file completely to your liking, but it should at least + contain the root `toctree` directive. + +Welcome to OpenHTF's documentation! +=================================== + +.. toctree:: + :maxdepth: 2 + :caption: Contents: + + + +Indices and tables +================== + +* :ref:`genindex` +* :ref:`modindex` +* :ref:`search` From b7a48a1413fc846f3973127a019b3013376cca51 Mon Sep 17 00:00:00 2001 From: Dan Lipsitt Date: Thu, 10 Aug 2017 16:21:48 -0700 Subject: [PATCH 2/7] Document how to build the Sphinx docs. --- .gitignore | 1 + CONTRIBUTING.md | 18 ++++++++++++++++++ 2 files changed, 19 insertions(+) diff --git a/.gitignore b/.gitignore index 3a3161c23..762f7f13d 100644 --- a/.gitignore +++ b/.gitignore @@ -44,3 +44,4 @@ other_modules/ # Tox temporary files .tox/ +/docs/_build diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 137d27333..6319aa955 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -334,3 +334,21 @@ npm run update_prebuilt That last step is easy to forget, so try to make it a habit whenever you're prepping a PR that includes frontend work. + +## Building documentation + +The documentation compiler loads each module to look for +docstrings. That means you need dependencies installed, including +optional ones: + +``` shellsession +pip install -e .[usb_plugs] +``` + +You can then build the docs: + +``` shellsession +python setup.py build_sphinx +``` + +The main index page will then be at `docs/build/html/index.html`. From 798aab353114469b62405c9fdcc3a9c17be0421b Mon Sep 17 00:00:00 2001 From: Dan Lipsitt Date: Thu, 10 Aug 2017 16:26:29 -0700 Subject: [PATCH 3/7] Enable the Sphinx extension that parses Google-style docstrings. --- docs/source/conf.py | 11 +++++++---- 1 file changed, 7 insertions(+), 4 deletions(-) diff --git a/docs/source/conf.py b/docs/source/conf.py index 73682ed5b..0af5a511a 100644 --- a/docs/source/conf.py +++ b/docs/source/conf.py @@ -24,14 +24,17 @@ # -- General configuration ------------------------------------------------ # If your documentation needs a minimal Sphinx version, state it here. -# -# needs_sphinx = '1.0' + +needs_sphinx = '1.3' # for napoleon # Add any Sphinx extension module names here, as strings. They can be # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom # ones. -extensions = ['sphinx.ext.autodoc', - 'sphinx.ext.viewcode'] +extensions = [ + 'sphinx.ext.autodoc', + 'sphinx.ext.viewcode', + 'sphinx.ext.napoleon', +] # Add any paths that contain templates here, relative to this directory. templates_path = ['_templates'] From e181aec049044ffbc82e1c0abe078cfdb9036b27 Mon Sep 17 00:00:00 2001 From: Dan Lipsitt Date: Sun, 20 Aug 2017 14:55:28 -0700 Subject: [PATCH 4/7] Use pbr to generate api docs. --- setup.cfg | 5 +++++ setup.py | 3 ++- 2 files changed, 7 insertions(+), 1 deletion(-) diff --git a/setup.cfg b/setup.cfg index 5e4090017..86bc6a397 100644 --- a/setup.cfg +++ b/setup.cfg @@ -1,2 +1,7 @@ +[metadata] +name = openhtf +url = https://github.com/google/openhtf +[pbr] +autodoc_index_modules = true [wheel] universal = 1 diff --git a/setup.py b/setup.py index 6d403a4e7..7cfc08986 100644 --- a/setup.py +++ b/setup.py @@ -159,7 +159,7 @@ def run_tests(self): setup( - name='openhtf', + pbr=True, version='1.1.0', description='OpenHTF, the open hardware testing framework.', author='John Hawley', @@ -186,6 +186,7 @@ def run_tests(self): ], }, setup_requires=[ + 'pbr', 'wheel>=0.29.0,<1.0', ], tests_require=[ From 3a91d4e6fead9ff77d892457e82311d2421426aa Mon Sep 17 00:00:00 2001 From: Dan Lipsitt Date: Sun, 20 Aug 2017 15:36:35 -0700 Subject: [PATCH 5/7] Set pbr autogenerated docs dir. --- .gitignore | 7 ++++++- setup.cfg | 3 +++ 2 files changed, 9 insertions(+), 1 deletion(-) diff --git a/.gitignore b/.gitignore index 762f7f13d..2eeaa5b6e 100644 --- a/.gitignore +++ b/.gitignore @@ -44,4 +44,9 @@ other_modules/ # Tox temporary files .tox/ -/docs/_build + +# Sphinx docs +/docs/build +# autogenerated by pbr +/docs/source/api + diff --git a/setup.cfg b/setup.cfg index 86bc6a397..1f75ecaa2 100644 --- a/setup.cfg +++ b/setup.cfg @@ -3,5 +3,8 @@ name = openhtf url = https://github.com/google/openhtf [pbr] autodoc_index_modules = true +[build_sphinx] +source_dir = docs/source +build_dir = docs/build [wheel] universal = 1 From ada2368575141c2580e6a9f308b72dc865a29e48 Mon Sep 17 00:00:00 2001 From: Dan Lipsitt Date: Sun, 20 Aug 2017 17:13:15 -0700 Subject: [PATCH 6/7] Add api docs to index. --- docs/source/index.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/source/index.rst b/docs/source/index.rst index 7197e3bf1..b2f65b171 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -10,7 +10,7 @@ Welcome to OpenHTF's documentation! :maxdepth: 2 :caption: Contents: - + api/autoindex Indices and tables ================== From 88b01eb3b9aa513eb2d62f01b856e8e22c4a9eca Mon Sep 17 00:00:00 2001 From: Dan Lipsitt Date: Mon, 4 Sep 2017 19:10:22 -0700 Subject: [PATCH 7/7] Add documentation build to tox. --- tox.ini | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/tox.ini b/tox.ini index 61369a961..218d0f3a0 100644 --- a/tox.ini +++ b/tox.ini @@ -9,3 +9,8 @@ commands = {envbindir}/python setup.py build_proto # Instead, it does 'python setup.py develop' which only adds openhtf/ to the # path. usedevelop = True + +[testenv:docs] +deps=sphinx +commands= + {envbindir}/setup.py build_sphinx