Browse Source

Publish release notes

Since we have release notes for bindep, we should publish them
alongside our documentation. Also update to more modern patterns for
invoking Sphinx, splitting documentation build requirements to their
own file. Drop use of the openstackdocstheme and just rely on the
default Alibaster theme like other OpenDev tools do. Remove a few
other OpenStackisms in the Sphinx configuration too, and drop the
autogenerated date included in the copyright value (not only is it
unnecessary, it's bad practice from a rebuildability standpoint, and
inaccurate since the date docs were built is not necessarily the
date the content was written).

Change-Id: I84ab856dc92d0546653fe7ca7c4e9683835c9c4a
changes/95/773795/1
Jeremy Stanley 1 year ago
parent
commit
5a1fb0fbfe
  1. 8
      doc/requirements.txt
  2. 25
      doc/source/conf.py
  3. 1
      doc/source/index.rst
  4. 6
      doc/source/releasenotes.rst
  5. 4
      test-requirements.txt
  6. 6
      tox.ini

8
doc/requirements.txt

@ -0,0 +1,8 @@
reno>=2.8.0 # Apache-2.0
sphinx!=1.6.6,!=1.6.7,<2.0.0;python_version=='2.7' # BSD
sphinx!=1.6.6,!=1.6.7,!=2.1.0;python_version>='3.4' # BSD
sphinxcontrib-programoutput # BSD license
# needed because we use autodoc to document our tests in the dev docs
fixtures>=0.3.12
mock>=2.0 # BSD

25
doc/source/conf.py

@ -12,7 +12,6 @@
# See the License for the specific language governing permissions and
# limitations under the License.
import datetime
import os
import sys
@ -24,15 +23,9 @@ sys.path.insert(0, os.path.abspath('../..'))
extensions = [
'sphinx.ext.autodoc',
'sphinxcontrib.programoutput',
'openstackdocstheme'
'reno.sphinxext',
]
# Setting for openstackdocstheme
html_theme = 'openstackdocs'
repository_name = 'openstack-infra/bindep'
bug_tag = ''
use_storyboard = True
# autodoc generation is a bit aggressive and a nuisance when doing heavy
# text edit cycles.
# execute "export SPHINX_DEBUG=1" in your terminal to disable
@ -45,7 +38,7 @@ master_doc = 'index'
# General information about the project.
project = u'bindep'
copyright = u"%d, OpenStack Foundation" % datetime.datetime.now().year
copyright = u"OpenDev Contributors"
# If true, '()' will be appended to :func: etc. cross-reference text.
add_function_parentheses = True
@ -75,8 +68,20 @@ latex_documents = [
('index',
'%s.tex' % project,
u'%s Documentation' % project,
u'OpenStack Foundation', 'manual'),
u'OpenDev Contributors', 'manual'),
]
# Example configuration for intersphinx: refer to the Python standard library.
#intersphinx_mapping = {'http://docs.python.org/': None}
# -- Options for manual page output --------------------------------------------
# One entry per manual page. List of tuples
# (source start file, name, description, authors, manual section).
man_pages = [
('index', 'bindep', u'Bindep Documentation', [u'OpenDev Contributors'], 1),
]
# If true, show URL addresses after external links.
#man_show_urls = False

1
doc/source/index.rst

@ -14,6 +14,7 @@ Contents:
installation
usage
contributing
releasenotes
Indices and tables
==================

6
doc/source/releasenotes.rst

@ -0,0 +1,6 @@
=============
Release Notes
=============
.. release-notes::
:unreleased-version-title: In Development

4
test-requirements.txt

@ -4,7 +4,3 @@ mock>=2.0 # BSD
python-subunit
testrepository>=0.0.13
testtools>=0.9.27
sphinx!=1.6.6,!=1.6.7,<2.0.0;python_version=='2.7' # BSD
sphinx!=1.6.6,!=1.6.7,!=2.1.0;python_version>='3.4' # BSD
openstackdocstheme>=1.24.1 # Apache-2.0
sphinxcontrib-programoutput # BSD license

6
tox.ini

@ -26,7 +26,11 @@ commands = {posargs}
commands = python setup.py test --coverage --testr-args='{posargs}'
[testenv:docs]
commands = sphinx-build -W -b html doc/source doc/build/html
deps =
-r{toxinidir}/requirements.txt
-r{toxinidir}/doc/requirements.txt
commands =
sphinx-build -W -d doc/build/doctrees -b html doc/source/ doc/build/html
[flake8]
# E123, E125 skipped as they are invalid PEP-8.

Loading…
Cancel
Save