diff --git a/.circleci/config.yml b/.circleci/config.yml index d4ad8c6a0..2a4ede411 100644 --- a/.circleci/config.yml +++ b/.circleci/config.yml @@ -193,13 +193,6 @@ jobs: - TEST_WHEELINSTALL_ENV: "wheelinstall-py37" <<: *conda-steps - gallery35: - docker: - - image: circleci/python:3.5.7-jessie - environment: - - TEST_TOX_ENV: "gallery-py35" - <<: *gallery-steps - gallery36: docker: - image: circleci/python:3.6.3-jessie @@ -279,8 +272,6 @@ workflows: <<: *no_filters - miniconda37: <<: *no_filters - - gallery35: - <<: *no_filters - gallery36: <<: *no_filters - gallery37: @@ -294,7 +285,6 @@ workflows: - miniconda35 - miniconda36 - miniconda37 - - gallery35 - gallery36 - gallery37 filters: @@ -314,7 +304,6 @@ workflows: - miniconda35 - miniconda36 - miniconda37 - - gallery35 - gallery36 - gallery37 filters: diff --git a/docs/Makefile b/docs/Makefile index b22e1ffe5..ece536eae 100644 --- a/docs/Makefile +++ b/docs/Makefile @@ -9,12 +9,12 @@ PAPER = BUILDDIR = _build SRCDIR = ../src RSTDIR = source -PKGNAME = {pynwb,form} +PKGNAME = pynwb # Internal variables. PAPEROPT_a4 = -D latex_paper_size=a4 PAPEROPT_letter = -D latex_paper_size=letter -ALLSPHINXOPTS = -d $(BUILDDIR)/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) source +ALLSPHINXOPTS = -d $(BUILDDIR)/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) $(RSTDIR) # the i18n builder cannot share the environment and doctrees with the others I18NSPHINXOPTS = $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) . @@ -41,10 +41,11 @@ help: @echo " changes to make an overview of all changed/added/deprecated items" @echo " linkcheck to check all external links for integrity" @echo " doctest to run all doctests embedded in the documentation (if enabled)" - @echo " apidoc to to build RST from source code" + @echo " clean to clean all documents built by Sphinx in _build" + @echo " apidoc to build RST from source code" clean: - -rm -rf $(BUILDDIR)/* $(RSTDIR)/$(PKGNAME)*.rst $(RSTDIR)/modules.rst + -rm -rf $(BUILDDIR)/* $(RSTDIR)/$(PKGNAME)*.rst html: $(SPHINXBUILD) -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html @@ -158,6 +159,5 @@ doctest: "results in $(BUILDDIR)/doctest/output.txt." apidoc: - $(SPHINXAPIDOC) -f -e -o $(RSTDIR) $(SRCDIR) + $(SPHINXAPIDOC) -f -e --no-toc -o $(RSTDIR) $(SRCDIR) @echo "Build rst docs from source code." - diff --git a/docs/gallery/domain/brain_observatory.py b/docs/gallery/domain/brain_observatory.py index c8d9ac014..469683503 100644 --- a/docs/gallery/domain/brain_observatory.py +++ b/docs/gallery/domain/brain_observatory.py @@ -9,6 +9,8 @@ # This example demostrates the basic functionality of several parts of the pynwb write API, centered around the optical # physiology submodule (pynwb.ophys). We will use the allensdk as a read API, while leveraging the pynwb data model and # write api to transform and write the data back to disk. +# +# .. note: Using the latest allensdk package requires Python 3.6 or higher. ######################################## # .. raw:: html diff --git a/docs/make.bat b/docs/make.bat index deed45a8d..b50d10f3a 100644 --- a/docs/make.bat +++ b/docs/make.bat @@ -5,8 +5,14 @@ REM Command file for Sphinx documentation if "%SPHINXBUILD%" == "" ( set SPHINXBUILD=sphinx-build ) +if "%SPHINXAPIDOC%" == "" ( + set SPHINXAPIDOC=sphinx-apidoc +) set BUILDDIR=_build -set ALLSPHINXOPTS=-d %BUILDDIR%/doctrees %SPHINXOPTS% . +set RSTDIR=source +set SRCDIR=../src +set PKGNAME=pynwb +set ALLSPHINXOPTS=-d %BUILDDIR%/doctrees %SPHINXOPTS% %RSTDIR% set I18NSPHINXOPTS=%SPHINXOPTS% . if NOT "%PAPER%" == "" ( set ALLSPHINXOPTS=-D latex_paper_size=%PAPER% %ALLSPHINXOPTS% @@ -35,12 +41,15 @@ if "%1" == "help" ( echo. changes to make an overview over all changed/added/deprecated items echo. linkcheck to check all external links for integrity echo. doctest to run all doctests embedded in the documentation if enabled + echo. clean to clean all documents built by Sphinx in _build + echo. apidoc to build RST from source code" goto end ) if "%1" == "clean" ( for /d %%i in (%BUILDDIR%\*) do rmdir /q /s %%i del /q /s %BUILDDIR%\* + del /q %RSTDIR%\%PKGNAME%*.rst goto end ) @@ -187,4 +196,12 @@ results in %BUILDDIR%/doctest/output.txt. goto end ) +if "%1" == "apidoc" ( + %SPHINXAPIDOC% -f -e --no-toc -o %RSTDIR% %SRCDIR% + if errorlevel 1 exit /b 1 + echo. + echo.Build rst docs from source code. + goto end +) + :end diff --git a/docs/source/conf.py b/docs/source/conf.py index 162d19544..6cbe0e752 100644 --- a/docs/source/conf.py +++ b/docs/source/conf.py @@ -14,7 +14,6 @@ import sys import os import sphinx_rtd_theme -from sphinx.domains.python import PythonDomain # -- Support building doc without install -------------------------------------- @@ -71,9 +70,8 @@ } intersphinx_mapping = { - 'python': ('https://docs.python.org/3.5', None), + 'python': ('https://docs.python.org/3.8', None), 'numpy': ('https://docs.scipy.org/doc/numpy/', None), - 'scipy': ('https://docs.scipy.org/doc/scipy/reference', None), 'matplotlib': ('https://matplotlib.org', None), 'h5py': ('http://docs.h5py.org/en/latest/', None), 'hdmf': ('https://hdmf.readthedocs.io/en/latest/', None), @@ -173,7 +171,7 @@ # The name of an image file (within the static path) to use as favicon of the # docs. This file should be a Windows icon file (.ico) being 16x16 or 32x32 # pixels large. -html_favicon = 'favicon-96.png' +html_favicon = 'favicon_96.png' # 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, @@ -247,7 +245,7 @@ # The name of an image file (relative to this directory) to place at the top of # the title page. -# latex_logo = None +latex_logo = 'logo.pdf' # For "manual" documents, if this is true, then toplevel headings are parts, # not chapters. @@ -307,27 +305,17 @@ # def run_apidoc(_): - from sphinx.apidoc import main + from sphinx.ext.apidoc import main as apidoc_main import os import sys out_dir = os.path.dirname(__file__) src_dir = os.path.join(out_dir, '../../src') sys.path.append(src_dir) - main(['-f', '-e', '-o', out_dir, src_dir]) - - -# https://github.com/sphinx-doc/sphinx/issues/3866 -class PatchedPythonDomain(PythonDomain): - def resolve_xref(self, env, fromdocname, builder, typ, target, node, contnode): - if 'refspecific' in node: - del node['refspecific'] - return super(PatchedPythonDomain, self).resolve_xref( - env, fromdocname, builder, typ, target, node, contnode) + apidoc_main(['-f', '-e', '--no-toc', '-o', out_dir, src_dir]) from abc import abstractproperty - def skip(app, what, name, obj, skip, options): if isinstance(obj, abstractproperty) or getattr(obj, '__isabstractmethod__', False): return False @@ -339,5 +327,4 @@ def skip(app, what, name, obj, skip, options): def setup(app): app.connect('builder-inited', run_apidoc) app.add_stylesheet("theme_overrides.css") # overrides for wide tables in RTD theme - app.override_domain(PatchedPythonDomain) app.connect("autodoc-skip-member", skip) diff --git a/docs/source/logo.pdf b/docs/source/logo.pdf new file mode 100644 index 000000000..6899de20f Binary files /dev/null and b/docs/source/logo.pdf differ diff --git a/requirements-doc.txt b/requirements-doc.txt index aa1bfeed7..8dee1a3be 100644 --- a/requirements-doc.txt +++ b/requirements-doc.txt @@ -1,8 +1,7 @@ -sphinx==1.8.5 +sphinx matplotlib -pillow sphinx_rtd_theme sphinx-gallery -allensdk==0.16.3 -tables==3.5.2 +Glymur==0.8.19 # required for allensdk 1.3.0 to work +allensdk==1.3.0 -r requirements.txt diff --git a/tox.ini b/tox.ini index da02067f9..b4eca5230 100644 --- a/tox.ini +++ b/tox.ini @@ -80,18 +80,11 @@ deps = commands = python test.py --example -[testenv:gallery-py35] -basepython = python3.5 -deps = {[testenv:gallery]deps} -commands = {[testenv:gallery]commands} - - [testenv:gallery-py36] basepython = python3.6 deps = {[testenv:gallery]deps} commands = {[testenv:gallery]commands} - [testenv:gallery-py37] basepython = python3.7 deps = {[testenv:gallery]deps}