diff --git a/.travis-tox.ini b/.travis-tox.ini index 8dcdd437ddb..5c384e0fbbe 100644 --- a/.travis-tox.ini +++ b/.travis-tox.ini @@ -33,6 +33,7 @@ envlist = style sdist bdist_wheel + api {py27,py34,py35,py36,pypy,pypy3}-cover {py27,py34,py35,py36,pypy,pypy3}-nocov @@ -131,3 +132,24 @@ deps = numpy commands = python setup.py bdist_wheel + +[testenv:api] +# Note Sphinx likes to have the code installed so can import it +skip_install = False +whitelist_externals = + bash + sphinx-apidoc + make +deps = + mmtf-python + mysql-connector-python-rf + numpy + rdflib + reportlab + scipy + sphinx>=1.8.0 + numpydoc +commands = + bash -c \'python setup.py install > /dev/null\' + bash -c \'mkdir -p Doc/api/_templates Doc/api/_static Doc/api/_build\' + make -C Doc/api/ html diff --git a/.travis.yml b/.travis.yml index f2d06b2bafc..791aca7eeb6 100644 --- a/.travis.yml +++ b/.travis.yml @@ -38,6 +38,13 @@ matrix: apt: packages: before_install: echo "Going to run basic checks" + - stage: test + python: 2.7 + env: TOXENV=api + addons: + apt: + packages: + before_install: echo "Going to build API docs" - stage: test python: 2.7 env: TOXENV=py27-cover @@ -145,7 +152,7 @@ install: - tox -c .travis-tox.ini -e $TOXENV --notest script: - - travis_wait tox -c .travis-tox.ini -e $TOXENV + - travis_wait 30 tox -c .travis-tox.ini -e $TOXENV notifications: email: false diff --git a/Doc/api/Makefile b/Doc/api/Makefile new file mode 100644 index 00000000000..208e32f6e16 --- /dev/null +++ b/Doc/api/Makefile @@ -0,0 +1,20 @@ +# Minimal makefile for Sphinx documentation +# + +# You can set these variables from the command line. +SPHINXOPTS = +SPHINXBUILD = sphinx-build +SPHINXPROJ = Bio +SOURCEDIR = . +BUILDDIR = _build + +# Put it first so that "make" without argument is like "make help". +help: + @$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) + +.PHONY: help Makefile + +# Catch-all target: route all unknown targets to Sphinx using the new +# "make mode" option. $(O) is meant as a shortcut for $(SPHINXOPTS). +%: Makefile + @$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) diff --git a/Doc/api/conf.py b/Doc/api/conf.py new file mode 100644 index 00000000000..6c9e69e9ffd --- /dev/null +++ b/Doc/api/conf.py @@ -0,0 +1,234 @@ +#!/usr/bin/env python3 +# -*- coding: utf-8 -*- +"""Biopython Sphinx documentation build configuration file. + +After generating ``*.rst`` files from the source code, this +file controls running ``sphinx-build`` to turn these into +human readable documentation. +""" + +import os +import shutil +# import sys +import tempfile + +from Bio import __version__ + +# -- General configuration ------------------------------------------------ + +# If your documentation needs a minimal Sphinx version, state it here. +# +# needs_sphinx = '1.0' +needs_sphinx = '1.8' + +# 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.todo', + 'sphinx.ext.viewcode', + 'sphinx.ext.autosummary', + 'numpydoc'] + +# 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 = 'Biopython' +copyright = '1999-2017, The Biopython Contributors' +author = 'The Biopython Contributors' +document = 'Biopython API Documentation' + +# 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 = __version__ # TODO: Shorten this +# The full version, including alpha/beta/rc tags. +release = __version__ + +# 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 = ['_build', 'Thumbs.db', '.DS_Store'] + +# 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 = True + +# -- Options for autodoc -------------------------------------------------- + +# This requires Sphinx 1.8.0b1 or later: +autodoc_default_values = { + 'members': None, + 'undoc-members': None, + 'special-members': None, + 'show-inheritance': None, + 'member-order': 'bysource', + 'exclude-members': '__dict__,__weakref__,__module__', +} + +# To avoid import errors. +autodoc_mock_imports = ['MySQLdb'] + +# -- 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 = 'Biopython_doc' + + +# -- 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, 'Biopython_API.tex', document, author, '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, 'biopython', document, [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, 'Biopython', document, author, 'Biopython', + 'Collection of modules for dealing with biological data in Python.', + 'Miscellaneous'), +] + + +# -- Options for Epub output ---------------------------------------------- + +# Bibliographic Dublin Core info. +epub_title = document # project +epub_author = author +epub_publisher = author +epub_copyright = copyright + +# The unique identifier of the text. This can be a ISBN number +# or the project homepage. +# +# epub_identifier = '' + +# A unique identification for the text. +# +# epub_uid = '' + +# A list of files that should not be packed into the epub file. +epub_exclude_files = ['search.html'] + +# -- Options for numpydoc ------------------------------------------------- + +numpydoc_class_members_toctree = False + +# -- Magic to run sphinx-apidoc automatically ----------------------------- + +# See https://github.com/rtfd/readthedocs.org/issues/1139 +# on which this is based. + + +def run_apidoc(_): + """Call sphinx-apidoc on Bio and BioSQL modules.""" + from sphinx.ext.apidoc import main as apidoc_main + cur_dir = os.path.abspath(os.path.dirname(__file__)) + # Can't see a better way than running apidoc twice, for Bio & BioSQL + # We don't care about the index.rst / conf.py (we have our own) + # or the Makefile / make.bat (effectively same) clashing, + # $ sphinx-apidoc -e -F -o /tmp/api/BioSQL BioSQL + # $ sphinx-apidoc -e -F -o /tmp/api/Bio Bio + tmp_path = tempfile.mkdtemp() + apidoc_main(['-e', '-F', '-o', tmp_path, '../../BioSQL']) + apidoc_main(['-e', '-F', '-o', tmp_path, '../../Bio']) + os.remove(os.path.join(tmp_path, 'index.rst')) # Using our own + for filename in os.listdir(tmp_path): + if filename.endswith(".rst"): + shutil.move(os.path.join(tmp_path, filename), + os.path.join(cur_dir, filename)) + shutil.rmtree(tmp_path) + + +def setup(app): + """Over-ride Sphinx setup to trigger sphinx-apidoc.""" + app.connect('builder-inited', run_apidoc) diff --git a/Doc/api/index.rst b/Doc/api/index.rst new file mode 100644 index 00000000000..97e4d12f058 --- /dev/null +++ b/Doc/api/index.rst @@ -0,0 +1,21 @@ +.. Biopython API documentation master file, based on sphinx-quickstart + This depends on having sphinx-apidoc run on both Bio and BioSQL to + generate the per-module/package RST file referenced here. + +Welcome to Biopython's API documentation! +========================================= + +.. toctree:: + :maxdepth: 4 + :caption: Contents: + + Bio + BioSQL + + +Indices and tables +================== + +* :ref:`genindex` +* :ref:`modindex` +* :ref:`search`