diff --git a/.bumpversion.cfg b/.bumpversion.cfg index ead7f4f..ef79e4c 100644 --- a/.bumpversion.cfg +++ b/.bumpversion.cfg @@ -9,3 +9,5 @@ tag_name = {new_version} [bumpversion:file:src/jupyter_contrib_nbextensions/__init__.py] +[bumpversion:file:docs/source/conf.py] + diff --git a/.gitignore b/.gitignore index c5e95d0..18f4997 100644 --- a/.gitignore +++ b/.gitignore @@ -15,6 +15,8 @@ coverage.xml # Sphinx documentation docs/_build +# auto-generated Sphinx files +docs/source/nbextensions.rst .idea diff --git a/.travis.yml b/.travis.yml index 0471d65..32b617e 100644 --- a/.travis.yml +++ b/.travis.yml @@ -19,6 +19,10 @@ matrix: - os: linux python: '3.4' env: TOXENV=lint + # check docs build correctly + - os: linux + python: '3.4' + env: TOXENV=docs # linux, various python and notebook versions - os: linux python: '3.4' diff --git a/docs/Makefile b/docs/Makefile deleted file mode 100644 index c035448..0000000 --- a/docs/Makefile +++ /dev/null @@ -1,199 +0,0 @@ -# Makefile for Sphinx documentation -# - -# You can set these variables from the command line. -SPHINXOPTS = -SPHINXBUILD = sphinx-build -PAPER = -BUILDDIR = build - -# User-friendly check for sphinx-build -ifeq ($(shell which $(SPHINXBUILD) >/dev/null 2>&1; echo $$?), 1) -$(error The '$(SPHINXBUILD)' command was not found. Make sure you have Sphinx installed, then set the SPHINXBUILD environment variable to point to the full path of the '$(SPHINXBUILD)' executable. Alternatively you can add the directory with the executable to your PATH. If you don't have Sphinx installed, grab it from http://sphinx-doc.org/) -endif - -# Internal variables. -PAPEROPT_a4 = -D latex_paper_size=a4 -PAPEROPT_letter = -D latex_paper_size=letter -ALLSPHINXOPTS = -d $(BUILDDIR)/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) source -# the i18n builder cannot share the environment and doctrees with the others -I18NSPHINXOPTS = $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) source - -.PHONY: help clean rst html dirhtml singlehtml pickle json htmlhelp qthelp devhelp epub latex latexpdf text man changes linkcheck doctest coverage gettext - -help: - @echo "Please use \`make ' where is one of" - @echo " html to make standalone HTML files" - @echo " dirhtml to make HTML files named index.html in directories" - @echo " singlehtml to make a single large HTML file" - @echo " pickle to make pickle files" - @echo " json to make JSON files" - @echo " htmlhelp to make HTML files and a HTML help project" - @echo " qthelp to make HTML files and a qthelp project" - @echo " applehelp to make an Apple Help Book" - @echo " devhelp to make HTML files and a Devhelp project" - @echo " epub to make an epub" - @echo " latex to make LaTeX files, you can set PAPER=a4 or PAPER=letter" - @echo " latexpdf to make LaTeX files and run them through pdflatex" - @echo " latexpdfja to make LaTeX files and run them through platex/dvipdfmx" - @echo " text to make text files" - @echo " man to make manual pages" - @echo " texinfo to make Texinfo files" - @echo " info to make Texinfo files and run them through makeinfo" - @echo " gettext to make PO message catalogs" - @echo " changes to make an overview of all changed/added/deprecated items" - @echo " xml to make Docutils-native XML files" - @echo " pseudoxml to make pseudoxml-XML files for display purposes" - @echo " linkcheck to check all external links for integrity" - @echo " doctest to run all doctests embedded in the documentation (if enabled)" - @echo " coverage to run coverage check of the documentation (if enabled)" - -clean: - rm -rf $(BUILDDIR)/* - rm -rf source/nbextensions.rst - rm -R `ls -1 -d source/*/` - -source/nbextensions.rst: - python source/md2rst.py - @echo - @echo "Converting readme markdown files to rst" - -html: source/nbextensions.rst - $(SPHINXBUILD) -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html - @echo - @echo "Build finished. The HTML pages are in $(BUILDDIR)/html." - -dirhtml: source/nbextensions.rst - $(SPHINXBUILD) -b dirhtml $(ALLSPHINXOPTS) $(BUILDDIR)/dirhtml - @echo - @echo "Build finished. The HTML pages are in $(BUILDDIR)/dirhtml." - -singlehtml: source/nbextensions.rst - $(SPHINXBUILD) -b singlehtml $(ALLSPHINXOPTS) $(BUILDDIR)/singlehtml - @echo - @echo "Build finished. The HTML page is in $(BUILDDIR)/singlehtml." - -pickle: source/nbextensions.rst - $(SPHINXBUILD) -b pickle $(ALLSPHINXOPTS) $(BUILDDIR)/pickle - @echo - @echo "Build finished; now you can process the pickle files." - -json: source/nbextensions.rst - $(SPHINXBUILD) -b json $(ALLSPHINXOPTS) $(BUILDDIR)/json - @echo - @echo "Build finished; now you can process the JSON files." - -htmlhelp: source/nbextensions.rst - $(SPHINXBUILD) -b htmlhelp $(ALLSPHINXOPTS) $(BUILDDIR)/htmlhelp - @echo - @echo "Build finished; now you can run HTML Help Workshop with the" \ - ".hhp project file in $(BUILDDIR)/htmlhelp." - -qthelp: source/nbextensions.rst - $(SPHINXBUILD) -b qthelp $(ALLSPHINXOPTS) $(BUILDDIR)/qthelp - @echo - @echo "Build finished; now you can run "qcollectiongenerator" with the" \ - ".qhcp project file in $(BUILDDIR)/qthelp, like this:" - @echo "# qcollectiongenerator $(BUILDDIR)/qthelp/nbconvert.qhcp" - @echo "To view the help file:" - @echo "# assistant -collectionFile $(BUILDDIR)/qthelp/nbconvert.qhc" - -applehelp: source/nbextensions.rst - $(SPHINXBUILD) -b applehelp $(ALLSPHINXOPTS) $(BUILDDIR)/applehelp - @echo - @echo "Build finished. The help book is in $(BUILDDIR)/applehelp." - @echo "N.B. You won't be able to view it unless you put it in" \ - "~/Library/Documentation/Help or install it in your application" \ - "bundle." - -devhelp: source/nbextensions.rst - $(SPHINXBUILD) -b devhelp $(ALLSPHINXOPTS) $(BUILDDIR)/devhelp - @echo - @echo "Build finished." - @echo "To view the help file:" - @echo "# mkdir -p $$HOME/.local/share/devhelp/nbconvert" - @echo "# ln -s $(BUILDDIR)/devhelp $$HOME/.local/share/devhelp/nbconvert" - @echo "# devhelp" - -epub: source/nbextensions.rst - $(SPHINXBUILD) -b epub $(ALLSPHINXOPTS) $(BUILDDIR)/epub - @echo - @echo "Build finished. The epub file is in $(BUILDDIR)/epub." - -latex: source/nbextensions.rst - $(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex - @echo - @echo "Build finished; the LaTeX files are in $(BUILDDIR)/latex." - @echo "Run \`make' in that directory to run these through (pdf)latex" \ - "(use \`make latexpdf' here to do that automatically)." - -latexpdf: source/nbextensions.rst - $(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex - @echo "Running LaTeX files through pdflatex..." - $(MAKE) -C $(BUILDDIR)/latex all-pdf - @echo "pdflatex finished; the PDF files are in $(BUILDDIR)/latex." - -latexpdfja: source/nbextensions.rst - $(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex - @echo "Running LaTeX files through platex and dvipdfmx..." - $(MAKE) -C $(BUILDDIR)/latex all-pdf-ja - @echo "pdflatex finished; the PDF files are in $(BUILDDIR)/latex." - -text: source/nbextensions.rst - $(SPHINXBUILD) -b text $(ALLSPHINXOPTS) $(BUILDDIR)/text - @echo - @echo "Build finished. The text files are in $(BUILDDIR)/text." - -man: source/nbextensions.rst - $(SPHINXBUILD) -b man $(ALLSPHINXOPTS) $(BUILDDIR)/man - @echo - @echo "Build finished. The manual pages are in $(BUILDDIR)/man." - -texinfo: source/nbextensions.rst - $(SPHINXBUILD) -b texinfo $(ALLSPHINXOPTS) $(BUILDDIR)/texinfo - @echo - @echo "Build finished. The Texinfo files are in $(BUILDDIR)/texinfo." - @echo "Run \`make' in that directory to run these through makeinfo" \ - "(use \`make info' here to do that automatically)." - -info: source/nbextensions.rst - $(SPHINXBUILD) -b texinfo $(ALLSPHINXOPTS) $(BUILDDIR)/texinfo - @echo "Running Texinfo files through makeinfo..." - make -C $(BUILDDIR)/texinfo info - @echo "makeinfo finished; the Info files are in $(BUILDDIR)/texinfo." - -gettext: source/nbextensions.rst - $(SPHINXBUILD) -b gettext $(I18NSPHINXOPTS) $(BUILDDIR)/locale - @echo - @echo "Build finished. The message catalogs are in $(BUILDDIR)/locale." - -changes: source/nbextensions.rst - $(SPHINXBUILD) -b changes $(ALLSPHINXOPTS) $(BUILDDIR)/changes - @echo - @echo "The overview file is in $(BUILDDIR)/changes." - -linkcheck: source/nbextensions.rst - $(SPHINXBUILD) -b linkcheck $(ALLSPHINXOPTS) $(BUILDDIR)/linkcheck - @echo - @echo "Link check complete; look for any errors in the above output " \ - "or in $(BUILDDIR)/linkcheck/output.txt." - -doctest: source/nbextensions.rst - $(SPHINXBUILD) -b doctest $(ALLSPHINXOPTS) $(BUILDDIR)/doctest - @echo "Testing of doctests in the sources finished, look at the " \ - "results in $(BUILDDIR)/doctest/output.txt." - -coverage: source/nbextensions.rst - $(SPHINXBUILD) -b coverage $(ALLSPHINXOPTS) $(BUILDDIR)/coverage - @echo "Testing of coverage in the sources finished, look at the " \ - "results in $(BUILDDIR)/coverage/python.txt." - -xml: source/nbextensions.rst - $(SPHINXBUILD) -b xml $(ALLSPHINXOPTS) $(BUILDDIR)/xml - @echo - @echo "Build finished. The XML files are in $(BUILDDIR)/xml." - -pseudoxml: source/nbextensions.rst - $(SPHINXBUILD) -b pseudoxml $(ALLSPHINXOPTS) $(BUILDDIR)/pseudoxml - @echo - @echo "Build finished. The pseudo-XML files are in $(BUILDDIR)/pseudoxml." diff --git a/docs/README.md b/docs/README.md index d0bc663..62f3dc3 100644 --- a/docs/README.md +++ b/docs/README.md @@ -1,40 +1,61 @@ -# Documenting jupyter_contrib_nbextensions +Documenting jupyter_contrib_nbextensions +======================================== -[Documentation for `jupyter_contrib_nbextensions`](https://jupyter_contrib_nbextensions.readthedocs.org/en/latest/) -is hosted on ReadTheDocs. +Documentation for `jupyter_contrib_nbextensions` +is [hosted on ReadTheDocs](https://jupyter_contrib_nbextensions.readthedocs.org/en/latest/). -## Build Documentation locally -1. Change directory to documentation root: +Building the documentation locally +---------------------------------- - $ cd docs +The easiest way to build the docs locally is to use the provided tox +environment, `docs`. Essentially this just installs the correct dependencies +into a vitrualenv, and calls `sphinx-build` with the correct arguments. +See the repo's [tox.ini](../tox.ini) for details. -2. Install requirements: +From the repository root: - $ pip install -r requirements.txt +1. Install tox: -3. Build documentation using Makefile for Linux and OS X: + $ pip install tox - $ make html +2. Run the tox environment: - or on Windows: + $ tox -e docs - $ make.bat html +3. Display the documentation locally by navigating to `build/html/index.html` + in your browser. -4. Display the documentation locally by navigating to - ``build/html/index.html`` in your browser: + Or alternatively you may run a local server to display the docs. + In Python 3: - Or alternatively you may run a local server to display - the docs. In Python 3: + $ python -m http.server 8000 - $ python -m http.server 8000 + Then, in your browser, go to `http://localhost:8000`. - In your browser, go to `http://localhost:8000`. -## Developing Documentation +Developing Documentation +------------------------ -### Helpful files and directories +Helpful files and directories: -* `source` directory - source for documentation -* `source/conf.py` - Sphinx build configuration file -* `source/md2rst.py` - Generates rst files from readme markdown files of individual extensions + * `source` directory - source files for documentation. + * [source/conf.py](source/conf.py) - Sphinx build configuration file. + * [source/autogen_scripts/autogen_nbextensions_list.py](source/autogen_scripts/autogen_nbextensions_list.py) - + Generates an rst file listing each of the provided nbextensions readmes. + +The readme files for each nbextension are incorporated into the documentation +by using pandoc to convert them into rst as part of the parsing step. +This is configured in the Sphinx configuration file (see above). + +In order to get the nbextensions' readmes to build in sphinx, they _must_ be +inside the docs `source_dir`. +As a result, we call sphinx-build with the repository root as the `source_dir`, +and specify `docs/source` as the config directory (where sphinx can find +`conf.py`). + +On ReadTheDocs, however, we _cannot_ specify a `source_dir` different from the +config directory. As an alternative, we use a symlink to bring the readmes into +the source directory. This would in principle be a better solution altogether, +but symlinks aren't supported on Windows without admin rights, so we have to +use the hack detailed above. diff --git a/docs/environment.yml b/docs/environment.yml deleted file mode 100644 index 35cb532..0000000 --- a/docs/environment.yml +++ /dev/null @@ -1,11 +0,0 @@ -name: nbextensions -channels: -- conda-forge -dependencies: -- pandoc -- pypandoc -- sphinx -- sphinx_rtd_theme -- pip: - - recommonmark - diff --git a/docs/make.bat b/docs/make.bat deleted file mode 100644 index 7824fa4..0000000 --- a/docs/make.bat +++ /dev/null @@ -1,272 +0,0 @@ -@ECHO OFF - -REM Command file for Sphinx documentation - -if "%SPHINXBUILD%" == "" ( - set SPHINXBUILD=sphinx-build -) -set BUILDDIR=build -set ALLSPHINXOPTS=-d %BUILDDIR%/doctrees %SPHINXOPTS% source -set I18NSPHINXOPTS=%SPHINXOPTS% source -if NOT "%PAPER%" == "" ( - set ALLSPHINXOPTS=-D latex_paper_size=%PAPER% %ALLSPHINXOPTS% - set I18NSPHINXOPTS=-D latex_paper_size=%PAPER% %I18NSPHINXOPTS% -) - -if "%1" == "" goto help - -if "%1" == "help" ( - :help - echo.Please use `make ^` where ^ is one of - echo. html to make standalone HTML files - echo. dirhtml to make HTML files named index.html in directories - echo. singlehtml to make a single large HTML file - echo. pickle to make pickle files - echo. json to make JSON files - echo. htmlhelp to make HTML files and a HTML help project - echo. qthelp to make HTML files and a qthelp project - echo. devhelp to make HTML files and a Devhelp project - echo. epub to make an epub - echo. latex to make LaTeX files, you can set PAPER=a4 or PAPER=letter - echo. text to make text files - echo. man to make manual pages - echo. texinfo to make Texinfo files - echo. gettext to make PO message catalogs - echo. changes to make an overview over all changed/added/deprecated items - echo. xml to make Docutils-native XML files - echo. pseudoxml to make pseudoxml-XML files for display purposes - echo. linkcheck to check all external links for integrity - echo. doctest to run all doctests embedded in the documentation if enabled - echo. coverage to run coverage check of the documentation if enabled - goto end -) - -if "%1" == "clean" ( - for /d %%i in (%BUILDDIR%\*) do rmdir /q /s %%i - del /q /s %BUILDDIR%\* - for /d %%i in (source\*) do rmdir /q /s %%i - if exist soruce\nbextensions.rst ( - del /q /s source\nbextensions.rst - ) - goto end -) - -if not exist source\nbextensions.rst ( - python source\md2rst.py - echo. - echo.Converting readme markdown files to rst -) - -REM Check if sphinx-build is available and fallback to Python version if any -%SPHINXBUILD% 2> nul -if errorlevel 9009 goto sphinx_python -goto sphinx_ok - -:sphinx_python - -set SPHINXBUILD=python -m sphinx.__init__ -%SPHINXBUILD% 2> nul -if errorlevel 9009 ( - echo. - echo.The 'sphinx-build' command was not found. Make sure you have Sphinx - echo.installed, then set the SPHINXBUILD environment variable to point - echo.to the full path of the 'sphinx-build' executable. Alternatively you - echo.may add the Sphinx directory to PATH. - echo. - echo.If you don't have Sphinx installed, grab it from - echo.http://sphinx-doc.org/ - exit /b 1 -) - -:sphinx_ok - - -if "%1" == "html" ( - %SPHINXBUILD% -b html %ALLSPHINXOPTS% %BUILDDIR%/html - if errorlevel 1 exit /b 1 - echo. - echo.Build finished. The HTML pages are in %BUILDDIR%/html. - goto end -) - -if "%1" == "dirhtml" ( - %SPHINXBUILD% -b dirhtml %ALLSPHINXOPTS% %BUILDDIR%/dirhtml - if errorlevel 1 exit /b 1 - echo. - echo.Build finished. The HTML pages are in %BUILDDIR%/dirhtml. - goto end -) - -if "%1" == "singlehtml" ( - %SPHINXBUILD% -b singlehtml %ALLSPHINXOPTS% %BUILDDIR%/singlehtml - if errorlevel 1 exit /b 1 - echo. - echo.Build finished. The HTML pages are in %BUILDDIR%/singlehtml. - goto end -) - -if "%1" == "pickle" ( - %SPHINXBUILD% -b pickle %ALLSPHINXOPTS% %BUILDDIR%/pickle - if errorlevel 1 exit /b 1 - echo. - echo.Build finished; now you can process the pickle files. - goto end -) - -if "%1" == "json" ( - %SPHINXBUILD% -b json %ALLSPHINXOPTS% %BUILDDIR%/json - if errorlevel 1 exit /b 1 - echo. - echo.Build finished; now you can process the JSON files. - goto end -) - -if "%1" == "htmlhelp" ( - %SPHINXBUILD% -b htmlhelp %ALLSPHINXOPTS% %BUILDDIR%/htmlhelp - if errorlevel 1 exit /b 1 - echo. - echo.Build finished; now you can run HTML Help Workshop with the ^ -.hhp project file in %BUILDDIR%/htmlhelp. - goto end -) - -if "%1" == "qthelp" ( - %SPHINXBUILD% -b qthelp %ALLSPHINXOPTS% %BUILDDIR%/qthelp - if errorlevel 1 exit /b 1 - echo. - echo.Build finished; now you can run "qcollectiongenerator" with the ^ -.qhcp project file in %BUILDDIR%/qthelp, like this: - echo.^> qcollectiongenerator %BUILDDIR%\qthelp\nbconvert.qhcp - echo.To view the help file: - echo.^> assistant -collectionFile %BUILDDIR%\qthelp\nbconvert.ghc - goto end -) - -if "%1" == "devhelp" ( - %SPHINXBUILD% -b devhelp %ALLSPHINXOPTS% %BUILDDIR%/devhelp - if errorlevel 1 exit /b 1 - echo. - echo.Build finished. - goto end -) - -if "%1" == "epub" ( - %SPHINXBUILD% -b epub %ALLSPHINXOPTS% %BUILDDIR%/epub - if errorlevel 1 exit /b 1 - echo. - echo.Build finished. The epub file is in %BUILDDIR%/epub. - goto end -) - -if "%1" == "latex" ( - %SPHINXBUILD% -b latex %ALLSPHINXOPTS% %BUILDDIR%/latex - if errorlevel 1 exit /b 1 - echo. - echo.Build finished; the LaTeX files are in %BUILDDIR%/latex. - goto end -) - -if "%1" == "latexpdf" ( - %SPHINXBUILD% -b latex %ALLSPHINXOPTS% %BUILDDIR%/latex - cd %BUILDDIR%/latex - make all-pdf - cd %~dp0 - echo. - echo.Build finished; the PDF files are in %BUILDDIR%/latex. - goto end -) - -if "%1" == "latexpdfja" ( - %SPHINXBUILD% -b latex %ALLSPHINXOPTS% %BUILDDIR%/latex - cd %BUILDDIR%/latex - make all-pdf-ja - cd %~dp0 - echo. - echo.Build finished; the PDF files are in %BUILDDIR%/latex. - goto end -) - -if "%1" == "text" ( - %SPHINXBUILD% -b text %ALLSPHINXOPTS% %BUILDDIR%/text - if errorlevel 1 exit /b 1 - echo. - echo.Build finished. The text files are in %BUILDDIR%/text. - goto end -) - -if "%1" == "man" ( - %SPHINXBUILD% -b man %ALLSPHINXOPTS% %BUILDDIR%/man - if errorlevel 1 exit /b 1 - echo. - echo.Build finished. The manual pages are in %BUILDDIR%/man. - goto end -) - -if "%1" == "texinfo" ( - %SPHINXBUILD% -b texinfo %ALLSPHINXOPTS% %BUILDDIR%/texinfo - if errorlevel 1 exit /b 1 - echo. - echo.Build finished. The Texinfo files are in %BUILDDIR%/texinfo. - goto end -) - -if "%1" == "gettext" ( - %SPHINXBUILD% -b gettext %I18NSPHINXOPTS% %BUILDDIR%/locale - if errorlevel 1 exit /b 1 - echo. - echo.Build finished. The message catalogs are in %BUILDDIR%/locale. - goto end -) - -if "%1" == "changes" ( - %SPHINXBUILD% -b changes %ALLSPHINXOPTS% %BUILDDIR%/changes - if errorlevel 1 exit /b 1 - echo. - echo.The overview file is in %BUILDDIR%/changes. - goto end -) - -if "%1" == "linkcheck" ( - %SPHINXBUILD% -b linkcheck %ALLSPHINXOPTS% %BUILDDIR%/linkcheck - if errorlevel 1 exit /b 1 - echo. - echo.Link check complete; look for any errors in the above output ^ -or in %BUILDDIR%/linkcheck/output.txt. - goto end -) - -if "%1" == "doctest" ( - %SPHINXBUILD% -b doctest %ALLSPHINXOPTS% %BUILDDIR%/doctest - if errorlevel 1 exit /b 1 - echo. - echo.Testing of doctests in the sources finished, look at the ^ -results in %BUILDDIR%/doctest/output.txt. - goto end -) - -if "%1" == "coverage" ( - %SPHINXBUILD% -b coverage %ALLSPHINXOPTS% %BUILDDIR%/coverage - if errorlevel 1 exit /b 1 - echo. - echo.Testing of coverage in the sources finished, look at the ^ -results in %BUILDDIR%/coverage/python.txt. - goto end -) - -if "%1" == "xml" ( - %SPHINXBUILD% -b xml %ALLSPHINXOPTS% %BUILDDIR%/xml - if errorlevel 1 exit /b 1 - echo. - echo.Build finished. The XML files are in %BUILDDIR%/xml. - goto end -) - -if "%1" == "pseudoxml" ( - %SPHINXBUILD% -b pseudoxml %ALLSPHINXOPTS% %BUILDDIR%/pseudoxml - if errorlevel 1 exit /b 1 - echo. - echo.Build finished. The pseudo-XML files are in %BUILDDIR%/pseudoxml. - goto end -) - -:end diff --git a/docs/requirements.txt b/docs/requirements.txt index f7ba6bf..d3fb2c4 100644 --- a/docs/requirements.txt +++ b/docs/requirements.txt @@ -1,7 +1,6 @@ -pandoc -pypandoc +ipython +jupyter_nbextensions_configurator +readthedocs-sphinx-ext +recommonmark>=0.4.0 sphinx>=1.3.6 sphinx_rtd_theme -recommonmark==0.4.0 -entrypoints - diff --git a/docs/source/autogen_scripts/autogen_nbextensions_list.py b/docs/source/autogen_scripts/autogen_nbextensions_list.py new file mode 100644 index 0000000..9fd1cb4 --- /dev/null +++ b/docs/source/autogen_scripts/autogen_nbextensions_list.py @@ -0,0 +1,70 @@ +#!/usr/bin/env python +""" +Create nbextensions.rst, a Sphinx documentation source file. + +Links to documentation for each of the nbextensions provided by the +jupyter_contrib_nbextensions package. +""" + +import logging +import os + +from jupyter_contrib_core.testing_utils import get_logger +from jupyter_nbextensions_configurator import get_configurable_nbextensions + +log = get_logger(name=os.path.basename(__file__), log_level=logging.INFO) + +# Set on_rtd to whether we are building on readthedocs. We get this test from +# docs.readthedocs.io +on_rtd = os.environ.get('READTHEDOCS', None) == 'True' +log.info('on_rtd = {}'.format(on_rtd)) + +doc_autogen_dir = os.path.dirname(__file__) +doc_srcdir = os.path.dirname(doc_autogen_dir) +doc_root = os.path.dirname(doc_srcdir) +pkg_root = os.path.dirname(doc_root) +destination = os.path.join(doc_root, 'source', 'nbextensions.rst') +nbext_dir = os.path.realpath(os.path.join( + pkg_root, 'src', 'jupyter_contrib_nbextensions', 'nbextensions')) + +log.info('doc_autogen_dir = {}'.format(doc_autogen_dir)) +log.info('doc_srcdir = {}'.format(doc_srcdir)) +log.info('doc_root = {}'.format(doc_root)) +log.info('pkg_root = {}'.format(pkg_root)) +log.info('nbext_dir = {}'.format(nbext_dir)) + +log.info('Writing Sphinx doc file {}'.format(destination)) + +# readthedocs doesn't allow us to specify the docs source_dir, but assumes +# it to be the same as the parent dir of this file. As such, we cheat for rtd +# by inserting a symlink, which requires us to alter the relative paths from +# the nbextensions.rst list to the readme files. +readme_rst_uri_prefix = ( + 'nbextensions/' if on_rtd else + '../../src/jupyter_contrib_nbextensions/nbextensions/') + +log.info('readme_rst_uri_prefix = {}'.format(readme_rst_uri_prefix)) +log.info('looking for nbextensions in {}...'.format(nbext_dir)) +nbextensions = sorted( + get_configurable_nbextensions([nbext_dir], log=log), + key=lambda a: a['Name'].lower()) + +header = """ + +.. This is an automatically generated file. Do not modify by hand. + +List of provided nbxtensions +============================ + +.. toctree:: + :maxdepth: 1 + +""" + +with open(destination, 'w') as f: + f.write(header) + f.writelines([ + ' {}\n'.format( + readme_rst_uri_prefix + os.path.splitext(nbext['readme'])[0]) + for nbext in nbextensions if nbext.get('readme') + ]) diff --git a/docs/source/conf.py b/docs/source/conf.py index ef9ebc9..f00fcd5 100644 --- a/docs/source/conf.py +++ b/docs/source/conf.py @@ -1,319 +1,185 @@ #!/usr/bin/env python3 # -*- coding: utf-8 -*- # -# nbconvert documentation build configuration file, created by -# sphinx-quickstart on Tue Jun 9 17:11:30 2015. -# -# 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. +# jupyter_contrib_nbextensions sphinx documentation build configuration file. +# This file gets execfile()d with the current directory set to its containing +# dir. +import datetime +import glob +import logging import os -from recommonmark.parser import CommonMarkParser + +from jupyter_contrib_core.testing_utils import get_logger from recommonmark.transform import AutoStructify +from recommonmark.parser import CommonMarkParser +log = get_logger(name=os.path.basename(__file__), log_level=logging.INFO) -# 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. -#sys.path.insert(0, os.path.abspath('.')) +# Set on_rtd to whether we are building on readthedocs. We get this test from +# docs.readthedocs.io +on_rtd = os.environ.get('READTHEDOCS', None) == 'True' +log.info('on_rtd = {}'.format(on_rtd)) -if os.environ.get('READTHEDOCS', ''): - # RTD doesn't use the repo's Makefile to build docs. We run - # autogen_config.py to create the config docs (i.e. Configuration Options - # page). - - with open('md2rst.py') as f: - exec(compile(f.read(), 'md2rst.py', 'exec'), {}) - - -# -- General configuration ------------------------------------------------ - -# If your documentation needs a minimal Sphinx version, state it here. -#needs_sphinx = '1.0' - -source_parsers = { - '.md': CommonMarkParser, +# mappings to other sphinx docs +intersphinx_mapping = { + 'ipython': ('http://ipython.org/ipython-doc/dev/', None), + 'nbconvert': ('http://nbconvert.readthedocs.io/en/latest/', None), + 'nbformat': ('http://nbformat.readthedocs.io/en/latest/', None), + 'jupyter': ('http://jupyter.readthedocs.io/en/latest/', None), } +# General information about the project. +project = 'jupyter_contrib_nbextensions' +copyright = '2015-{}, Jupyter Contrib Team'.format(datetime.date.today().year) +author = 'Jupyter Contrib Team' + +# 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 = '0.2.1' +# The full version, including alpha/beta/rc tags. +release = '0.2.1' + +# The suffix(es) of source filenames. +# You can specify multiple suffix as a list of strings +source_suffix = ['.rst', '.md'] +source_parsers = {'.md': CommonMarkParser} + +# List of patterns, relative to source directory, that match files and +# directories to ignore when looking for source files. +exclude_patterns = [ + '.ipynb_checkpoints', + '.tox', + 'build', + 'COPYING.rst', + 'dist', + 'docs/README.md', + 'example.ipynb', + 'README.md', + 'src/jupyter_contrib_nbextensions/nbextensions/exercise/history.md', + 'src/jupyter_contrib_nbextensions/nbextensions/latex_envs/doc/README.md', + ('src/jupyter_contrib_nbextensions/nbextensions/' + + 'slidemode/slidemode2/README.md'), + 'venv', +] + +# The master toctree document. +master_doc = 'docs/source/index' +if on_rtd: + # readthedocs doesn't allow us to specify the docs source_dir, but assumes + # it to be the same as the parent dir of this file. As such, we must adapt + # paths slightly: + master_doc = 'index' + # Add any Sphinx extension module names here, as strings. They can be # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom # ones. extensions = [ + 'IPython.sphinxext.ipython_console_highlighting', 'sphinx.ext.autodoc', + 'sphinx.ext.doctest', 'sphinx.ext.intersphinx', 'sphinx.ext.napoleon', + 'sphinx.ext.mathjax', ] -# 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', '.ipynb', '.md' ] - -# The encoding of source files. -#source_encoding = 'utf-8-sig' - -# The master toctree document. -master_doc = 'index' - -# General information about the project. -project = 'nbextensions' -from datetime import date -year = date.today().year -copyright = '2015-%s, Jupyter Contrib Team' % year -author = 'Jupyter Contrib Team' - -# 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 = None - -# There are two options for replacing |today|: either, you set today to some -# non-false value, then it is used: -#today = '' -# Else, today_fmt is used as the format for a strftime call. -#today_fmt = '%B %d, %Y' - -# List of patterns, relative to source directory, that match files and -# directories to ignore when looking for source files. -exclude_patterns = ['.ipynb_checkpoints', 'example.ipynb'] - -# The reST default role (used for this markup: `text`) to use for all -# documents. -#default_role = None - -# If true, '()' will be appended to :func: etc. cross-reference text. -#add_function_parentheses = True - -# If true, the current module name will be prepended to all description -# unit titles (such as .. function::). -#add_module_names = True - -# If true, sectionauthor and moduleauthor directives will be shown in the -# output. They are ignored by default. -#show_authors = False - # The name of the Pygments (syntax highlighting) style to use. pygments_style = 'sphinx' -# A list of ignored prefixes for module index sorting. -#modindex_common_prefix = [] - -# If true, keep warnings as "system message" paragraphs in the built documents. -#keep_warnings = False - -# If true, `todo` and `todoList` produce output, else they produce nothing. -todo_include_todos = False - - -# -- Options for HTML output ---------------------------------------------- - -# Set on_rtd to whether we are building on readthedocs.org. We get this line of -# code grabbed from docs.readthedocs.org -on_rtd = os.environ.get('READTHEDOCS', None) == 'True' +# -- Options for HTML output -------------------------------------------------- if not on_rtd: # only import and set the theme if we're building docs locally import sphinx_rtd_theme html_theme = 'sphinx_rtd_theme' html_theme_path = [sphinx_rtd_theme.get_html_theme_path()] - # otherwise, readthedocs.org uses their default theme, so no need to specify it - -# The theme to use for HTML and HTML Help pages. See the documentation for -# a list of builtin themes. -#html_theme = 'sphinx_rtd_theme' - -# 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 themes here, relative to this directory. -#html_theme_path = [sphinx_rtd_theme.get_html_theme_path()] - -# The name for this set of Sphinx documents. If None, it defaults to -# " v documentation". -#html_title = None - -# A shorter title for the navigation bar. Default is the same as html_title. -#html_short_title = None - -# The name of an image file (relative to this directory) to place at the top -# of the sidebar. -#html_logo = None - -# 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 = None - -# 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'] - -# Add any extra paths that contain custom files (such as robots.txt or -# .htaccess) here, relative to this directory. These files are copied -# directly to the root of the documentation. -#html_extra_path = [] - -# If not '', a 'Last updated on:' timestamp is inserted at every page bottom, -# using the given strftime format. -#html_last_updated_fmt = '%b %d, %Y' - -# If true, SmartyPants will be used to convert quotes and dashes to -# typographically correct entities. -#html_use_smartypants = True - -# Custom sidebar templates, maps document names to template names. -#html_sidebars = {} - -# Additional templates that should be rendered to pages, maps page names to -# template names. -#html_additional_pages = {} - -# If false, no module index is generated. -#html_domain_indices = True - -# If false, no index is generated. -#html_use_index = True - -# If true, the index is split into individual pages for each letter. -#html_split_index = False - -# If true, links to the reST sources are added to the pages. -#html_show_sourcelink = True - -# If true, "Created using Sphinx" is shown in the HTML footer. Default is True. -#html_show_sphinx = True - -# If true, "(C) Copyright ..." is shown in the HTML footer. Default is True. -#html_show_copyright = True - -# If true, an OpenSearch description file will be output, and all pages will -# contain a tag referring to it. The value of this option must be the -# base URL from which the finished HTML is served. -#html_use_opensearch = '' - -# This is the file name suffix for HTML files (e.g. ".xhtml"). -#html_file_suffix = None - -# Language to be used for generating the HTML full-text search index. -# Sphinx supports the following languages: -# 'da', 'de', 'en', 'es', 'fi', 'fr', 'h', 'it', 'ja' -# 'nl', 'no', 'pt', 'ro', 'r', 'sv', 'tr' -#html_search_language = 'en' - -# A dictionary with options for the search language support, empty by default. -# Now only 'ja' uses this config value -#html_search_options = {'type': 'default'} - -# The name of a javascript file (relative to the configuration directory) that -# implements a search results scorer. If empty, the default will be used. -#html_search_scorer = 'scorer.js' - # Output file base name for HTML help builder. -htmlhelp_basename = 'nbconvertdoc' - -# -- 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', -} +htmlhelp_basename = project + '_doc' +# -- Options for LaTeX output ------------------------------------------------- # 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, 'nbextensions.tex', 'Contributed Notebook Extensions Documentation', - 'Jupyter Contrib Team', 'manual'), + (master_doc, project + '_doc.tex', + 'Jupyter-contrib Notebook Extensions Documentation', author, 'manual'), ] -# The name of an image file (relative to this directory) to place at the top of -# the title page. -#latex_logo = None - -# For "manual" documents, if this is true, then toplevel headings are parts, -# not chapters. -#latex_use_parts = False - -# If true, show page references after internal links. -#latex_show_pagerefs = False - -# If true, show URL addresses after external links. -#latex_show_urls = False - -# Documents to append as an appendix to all manuals. -#latex_appendices = [] - -# If false, no module index is generated. -#latex_domain_indices = True - - -# -- Options for manual page output --------------------------------------- - +# -- Options for man-page output ---------------------------------------------- # One entry per manual page. List of tuples # (source start file, name, description, authors, manual section). man_pages = [ - (master_doc, 'nbextensions', 'nbextensions Documentation', - [author], 1) + (master_doc, project, + 'Jupyter-contrib Notebook Extensions Documentation', [author], 1) ] -# If true, show URL addresses after external links. -#man_show_urls = False - - -# -- Options for Texinfo output ------------------------------------------- - +# -- 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, 'nbextensions', 'nbextensions Documentation', - author, 'nbextensions', 'Contributed Jupyter Notebook Extensions.', - 'Miscellaneous'), + (master_doc, project + '_doc', + 'Jupyter-contrib Notebook Extensions Documentation', author, + 'nbextensions', 'Contributed Jupyter Notebook Extensions.', + 'Miscellaneous'), ] -# Documents to append as an appendix to all manuals. -#texinfo_appendices = [] +# -- ReadTheDocs cheats ------------------------------------------------------- +# readthedocs doesn't allow us to specify the docs source_dir, but assumes +# it to be the same as the parent dir of this file. As such, we must cheat: +if on_rtd: + log.info('-------- on_rtd commencing symlink cheat') + doc_srcdir = os.path.dirname(__file__) + doc_root = os.path.dirname(doc_srcdir) + pkg_root = os.path.dirname(doc_root) + nbext_dir = os.path.join( + pkg_root, 'src', 'jupyter_contrib_nbextensions', 'nbextensions') + nbext_dir_symlink = os.path.join(doc_root, 'source', 'nbextensions') -# If false, no module index is generated. -#texinfo_domain_indices = True + log.info('- doc_srcdir = {}'.format(doc_srcdir)) + log.info('- doc_root = {}'.format(doc_root)) + log.info('- pkg_root = {}'.format(pkg_root)) + log.info('- nbext_dir = {}'.format(nbext_dir)) + log.info('- nbext_dir_symlink = {}'.format(nbext_dir_symlink)) + if os.path.exists(nbext_dir_symlink): + log.info('- removing {}'.format(nbext_dir_symlink)) + os.remove(nbext_dir_symlink) + log.info('- symlinking {} at {}'.format(nbext_dir, nbext_dir_symlink)) + os.symlink(nbext_dir, nbext_dir_symlink) + log.info('-------- on_rtd finished symlink cheat') -# How to display URL addresses: 'footnote', 'no', or 'inline'. -#texinfo_show_urls = 'footnote' +# -- Run our auto-generation scripts ------------------------------------------ +for autogen_path in glob.glob(os.path.join('autogen_scripts', '*.py')): + autogen_path = os.path.realpath(autogen_path) + log.info('> running autogen script {}'.format( + os.path.relpath(autogen_path, os.path.dirname(__file__)))) + with open(autogen_path) as f: + _code = compile(f.read(), autogen_path, 'exec') + exec(_code, {'__file__': autogen_path}) -# If true, do not generate a @detailmenu in the "Top" node's menu. -#texinfo_no_detailmenu = False - -# Example configuration for intersphinx: refer to the Python standard library. -intersphinx_mapping = {'https://docs.python.org/': None} def setup(app): - app.add_config_value('recommonmark_config', { - 'url_resolver': lambda url: 'abc' + url, - 'auto_toc_tree_section': 'Contents', - }, True) - app.add_transform(AutoStructify ) + if not on_rtd: + from readthedocs_ext.readthedocs import ReadtheDocsBuilder + app.add_builder(ReadtheDocsBuilder) + def resolve_url(url): + """Return path to code file given relative url.""" + github_root = ('https://github.com/ipython-contrib/' + + 'jupyter_contrib_nbextensions/blob/master/') + return github_root + url.replace(os.path.sep, '/') + + app.add_config_value('recommonmark_config', dict( + enable_auto_toc_tree=True, + auto_toc_tree_section='Contents', + enable_auto_doc_ref=True, + enable_math=True, + enable_inline_math=True, + url_resolver=resolve_url, + enable_eval_rst=False, + ), True) + app.add_transform(AutoStructify) diff --git a/docs/source/md2rst.py b/docs/source/md2rst.py deleted file mode 100644 index af30a81..0000000 --- a/docs/source/md2rst.py +++ /dev/null @@ -1,51 +0,0 @@ -# Use pandoc to convert readme md files to rst and copy images to a place sphinx can process them. -# Afterwards, generate a rst file with links to all extensions -import sys -import os -from shutil import copyfile -import pypandoc - -extensions = """ -List of Extensions -================== - -.. toctree:: - :maxdepth: 1 - -""" - -destination = 'source' -if not os.path.exists(destination): - destination = '.' -print('Copying converted docs to %s directory' % destination) -src_path = os.path.join(destination, '..', '..', 'src', 'jupyter_contrib_nbextensions', 'nbextensions') -for root, directories, filenames in os.walk(src_path): - for filename in filenames: - ext = os.path.splitext(filename) - if 'md' in ext[1]: - md_filename = os.path.join(root, filename) - rst_path = os.path.join(os.path.split(root)[-1]) - src_path = os.path.join(destination, rst_path) - if not os.path.exists(src_path): - os.mkdir(src_path) - rst_name = ext[0]+'.rst' - rst_filename = os.path.join(src_path, rst_name) - output = pypandoc.convert_file(md_filename, format='md', to='rst', outputfile=rst_filename) - extensions += ' %s/%s\n' % (rst_path, ext[0]) - # copy images - for root2, directories2, filenames2 in os.walk(root): - for name2 in filenames2: - ext2 = os.path.splitext(name2) - if ext2[1].strip('.').lower() in ['jpg', 'png', 'gif']: - src = os.path.join(root2, name2) - dst = os.path.join(src_path, name2) - print('Destination: %s' % dst) - copyfile(src, dst) - -# Write list of extensions -extname = os.path.join(destination, 'nbextensions.rst') -f = open(extname, 'w') -f.write(extensions) -f.write('\n') -f.close() - diff --git a/tox.ini b/tox.ini index 8da31b9..ea5e62e 100644 --- a/tox.ini +++ b/tox.ini @@ -16,8 +16,8 @@ basepython = py33: {env:TOXPYTHON:python3.3} py34: {env:TOXPYTHON:python3.4} py35: {env:TOXPYTHON:python3.5} - {docs,spell}: {env:TOXPYTHON:python2.7} - {appveyorartifacts,bump,check,clean,codecov,condarecipe,coveralls,lint,report,pypi_build,pypi_upload}: {env:TOXPYTHON:python3.4} + {spell}: {env:TOXPYTHON:python2.7} + {appveyorartifacts,bump,check,clean,codecov,condarecipe,coveralls,docs,lint,report,pypi_build,pypi_upload}: {env:TOXPYTHON:python3.4} setenv = PYTHONPATH={toxinidir}/tests PYTHONUNBUFFERED=yes @@ -60,8 +60,8 @@ commands = deps = -r{toxinidir}/docs/requirements.txt commands = - sphinx-build {posargs:-E} -b html docs dist/docs - sphinx-build -b linkcheck docs dist/docs + sphinx-build {posargs:-E} -T -b readthedocs -c docs/source . dist/docs + sphinx-build {posargs:-E} -T -b linkcheck -c docs/source . dist/docs [testenv:spell] skip_install = true