From 53437e4673771b4461b5757e99a79c72943645cd Mon Sep 17 00:00:00 2001 From: mbichoffe Date: Fri, 27 Jul 2018 16:31:30 -0700 Subject: [PATCH 01/20] Change 'make docs-install' command to install Sphinx and Twilio libraries and 'make docs' to run sphinx-apidoc --- Makefile | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/Makefile b/Makefile index 4436b22710..5c16691e68 100644 --- a/Makefile +++ b/Makefile @@ -27,10 +27,11 @@ cover: find tests -type d | xargs nosetests --with-coverage --cover-inclusive --cover-erase --cover-package=twilio docs-install: - . venv/bin/activate; pip install pdoc + . venv/bin/activate; pip install twilio sphinx docs: - . venv/bin/activate; pdoc twilio --overwrite --html --html-dir docs + . venv/bin/activate; sphinx-apidoc -f twilio -o docs/source + cd docs && make clean && make html release: . venv/bin/activate; python setup.py sdist upload From 200900d3090b4c6f906e8f50ce67ec8ff3799832 Mon Sep 17 00:00:00 2001 From: mbichoffe Date: Mon, 30 Jul 2018 14:58:41 -0700 Subject: [PATCH 02/20] update gitignore to ignore build directories --- .gitignore | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/.gitignore b/.gitignore index 806f2cad94..67a9010c30 100644 --- a/.gitignore +++ b/.gitignore @@ -23,7 +23,9 @@ pip-log.txt .DS_Store -docs/ +# sphinx build folder +_build +build/ # PyCharm/IntelliJ .idea From 98e6e19c346238686a4bdc7e0c91e8ebe733e12f Mon Sep 17 00:00:00 2001 From: mbichoffe Date: Mon, 30 Jul 2018 15:02:11 -0700 Subject: [PATCH 03/20] Add docs directory and Makefile --- docs/Makefile | 155 ++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 155 insertions(+) create mode 100644 docs/Makefile diff --git a/docs/Makefile b/docs/Makefile new file mode 100644 index 0000000000..83d3ca323d --- /dev/null +++ b/docs/Makefile @@ -0,0 +1,155 @@ +# Minimal makefile for Sphinx documentation +# + +# You can set these variables from the command line. +SPHINXOPTS = +SPHINXBUILD = sphinx-build +SPHINXPROJ = twilio-python +SOURCEDIR = source +BUILDDIR = build + +# internal variables +PAPEROPT_a4 = -D latex_paper_size=a4 +PAPEROPT_letter = -D latex_paper_size=letter +ALLSPHINXOPTS = -d $(BUILDDIR)/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) . +# the i18n builder cannot share the environment and doctrees with the others +I18NSPHINXOPTS = $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) . + +.PHONY: help clean html dirhtml singlehtml pickle json htmlhelp qthelp devhelp epub latex latexpdf text man changes linkcheck doctest 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 " 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 " 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 " linkcheck to check all external links for integrity" + @echo " doctest to run all doctests embedded in the documentation (if enabled)" + +clean: + -rm -rf $(BUILDDIR)/* + +html: + $(SPHINXBUILD) -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html + + @echo + @echo "Build finished. The HTML pages are in $(BUILDDIR)/html." + +dirhtml: + $(SPHINXBUILD) -b dirhtml $(ALLSPHINXOPTS) $(BUILDDIR)/dirhtml + @echo + @echo "Build finished. The HTML pages are in $(BUILDDIR)/dirhtml." + +singlehtml: + $(SPHINXBUILD) -b singlehtml $(ALLSPHINXOPTS) $(BUILDDIR)/singlehtml + @echo + @echo "Build finished. The HTML page is in $(BUILDDIR)/singlehtml." + +pickle: + $(SPHINXBUILD) -b pickle $(ALLSPHINXOPTS) $(BUILDDIR)/pickle + @echo + @echo "Build finished; now you can process the pickle files." + +json: + $(SPHINXBUILD) -b json $(ALLSPHINXOPTS) $(BUILDDIR)/json + @echo + @echo "Build finished; now you can process the JSON files." + +htmlhelp: + $(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: + $(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/PythonUtils.qhcp" + @echo "To view the help file:" + @echo "# assistant -collectionFile $(BUILDDIR)/qthelp/PythonUtils.qhc" + +devhelp: + $(SPHINXBUILD) -b devhelp $(ALLSPHINXOPTS) $(BUILDDIR)/devhelp + @echo + @echo "Build finished." + @echo "To view the help file:" + @echo "# mkdir -p $$HOME/.local/share/devhelp/PythonUtils" + @echo "# ln -s $(BUILDDIR)/devhelp $$HOME/.local/share/devhelp/PythonUtils" + @echo "# devhelp" + +epub: + $(SPHINXBUILD) -b epub $(ALLSPHINXOPTS) $(BUILDDIR)/epub + @echo + @echo "Build finished. The epub file is in $(BUILDDIR)/epub." + +latex: + $(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: + $(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." + +text: + $(SPHINXBUILD) -b text $(ALLSPHINXOPTS) $(BUILDDIR)/text + @echo + @echo "Build finished. The text files are in $(BUILDDIR)/text." + +man: + $(SPHINXBUILD) -b man $(ALLSPHINXOPTS) $(BUILDDIR)/man + @echo + @echo "Build finished. The manual pages are in $(BUILDDIR)/man." + +texinfo: + $(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: + $(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: + $(SPHINXBUILD) -b gettext $(I18NSPHINXOPTS) $(BUILDDIR)/locale + @echo + @echo "Build finished. The message catalogs are in $(BUILDDIR)/locale." + +changes: + $(SPHINXBUILD) -b changes $(ALLSPHINXOPTS) $(BUILDDIR)/changes + @echo + @echo "The overview file is in $(BUILDDIR)/changes." + +linkcheck: + $(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: + $(SPHINXBUILD) -b doctest $(ALLSPHINXOPTS) $(BUILDDIR)/doctest + @echo "Testing of doctests in the sources finished, look at the " \ + "results in $(BUILDDIR)/doctest/output.txt." From 6808032948fb27b0c6336829437e751bb46d50ac Mon Sep 17 00:00:00 2001 From: mbichoffe Date: Mon, 30 Jul 2018 15:02:29 -0700 Subject: [PATCH 04/20] add config file --- docs/conf.py | 190 +++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 190 insertions(+) create mode 100644 docs/conf.py diff --git a/docs/conf.py b/docs/conf.py new file mode 100644 index 0000000000..2427f024c8 --- /dev/null +++ b/docs/conf.py @@ -0,0 +1,190 @@ +# -*- coding: utf-8 -*- +# +# Configuration file for the Sphinx documentation builder. +# +# This file does only contain a selection of the most common options. For a +# full list see the documentation: +# http://www.sphinx-doc.org/en/master/config + +from twilio import __version__ + +# -- Path setup -------------------------------------------------------------- + +# 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.join(os.path.abspath('..'), 'twilio')) +# -- Project information ----------------------------------------------------- + +project = 'twilio-python' +copyright = '2018, Twilio' +author = 'Twilio' + +# The short X.Y version +version = __version__ +# The full version, including alpha/beta/rc tags +release = __version__ + + +# -- 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.doctest', + 'sphinx.ext.intersphinx', + 'sphinx.ext.coverage', + 'sphinx.ext.ifconfig', + 'sphinx.ext.viewcode', +] + +# Add any paths that contain templates here, relative to this directory. +templates_path = ['source/_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 = 'source/index' + +# 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 + +# List of patterns, relative to source directory, that match files and +# directories to ignore when looking for source files. +# This pattern also affects html_static_path and html_extra_path . +exclude_patterns = [] + +# The name of the Pygments (syntax highlighting) style to use. +pygments_style = 'sphinx' + + +# -- 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 = {} + +html_static_path = ['source/_static'] + +# Custom sidebar templates, must be a dictionary that maps document names +# to template names. +# +# The default sidebars (for documents that don't match any pattern) are +# defined by theme itself. Builtin themes are using these templates by +# default: ``['localtoc.html', 'relations.html', 'sourcelink.html', +# 'searchbox.html']``. +# +html_sidebars = { + '**': [ 'sidebarintro.html', 'localtoc.html', 'relations.html', + 'sourcelink.html', 'searchbox.html'] +} + + +# -- Options for HTMLHelp output --------------------------------------------- + +# Output file base name for HTML help builder. +htmlhelp_basename = 'twilio-pythondoc' + + +# -- 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, 'twilio-python.tex', 'twilio-python Documentation', + 'Twilio', '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, 'twilio-python', 'twilio-python 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, 'twilio-python', 'twilio-python Documentation', + author, 'twilio-python', 'One line description of project.', + 'Miscellaneous'), +] + + +# -- Options for Epub output ------------------------------------------------- + +# Bibliographic Dublin Core info. +epub_title = 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'] + + +# -- Extension configuration ------------------------------------------------- + +# -- Options for intersphinx extension --------------------------------------- + +# Example configuration for intersphinx: refer to the Python standard library. +intersphinx_mapping = {'https://docs.python.org/': None} \ No newline at end of file From fab86d05201cba00ad75907d2b3dd81f2ca975fc Mon Sep 17 00:00:00 2001 From: mbichoffe Date: Mon, 30 Jul 2018 15:03:04 -0700 Subject: [PATCH 05/20] add sidebar template; --- docs/source/_templates/sidebarintro.html | 11 +++++++++++ 1 file changed, 11 insertions(+) create mode 100644 docs/source/_templates/sidebarintro.html diff --git a/docs/source/_templates/sidebarintro.html b/docs/source/_templates/sidebarintro.html new file mode 100644 index 0000000000..a2eaf94ebc --- /dev/null +++ b/docs/source/_templates/sidebarintro.html @@ -0,0 +1,11 @@ +

About twilio-python

+

+ A Python module for communicating with the Twilio API and generating TwiML. +

+ +

Useful Links

+ \ No newline at end of file From 4061c61b412f07d8aa78fcf9f85c550a28c2fddf Mon Sep 17 00:00:00 2001 From: mbichoffe Date: Mon, 30 Jul 2018 15:03:34 -0700 Subject: [PATCH 06/20] adds index directive --- docs/source/index.rst | 36 ++++++++++++++++++++++++++++++++++++ 1 file changed, 36 insertions(+) create mode 100644 docs/source/index.rst diff --git a/docs/source/index.rst b/docs/source/index.rst new file mode 100644 index 0000000000..3fa569e4f4 --- /dev/null +++ b/docs/source/index.rst @@ -0,0 +1,36 @@ +.. twilio-python documentation master file, created by + sphinx-quickstart on Fri Jul 27 12:54:05 2018. + You can adapt this file completely to your liking, but it should at least + contain the root `toctree` directive. + + +Welcome to twilio-python's documentation! +========================================= + +Release v\ |version|. + +.. toctree:: + :maxdepth: 2 + + readme_include + + +API auto-generated documentation +================================ + +If you are looking for information on a specific function, class or +method, this part of the documentation is for you. + +.. toctree:: + :maxdepth: 2 + + modules + + +Indices and tables +================== + +* :ref:`genindex` +* :ref:`modindex` +* :ref:`search` + From a7f92bda0023b9bf41c195bb8103273137a84e7b Mon Sep 17 00:00:00 2001 From: mbichoffe Date: Mon, 30 Jul 2018 15:04:02 -0700 Subject: [PATCH 07/20] adds readme to autogenerated docs --- docs/source/readme_include.rst | 1 + 1 file changed, 1 insertion(+) create mode 100644 docs/source/readme_include.rst diff --git a/docs/source/readme_include.rst b/docs/source/readme_include.rst new file mode 100644 index 0000000000..38ba8043df --- /dev/null +++ b/docs/source/readme_include.rst @@ -0,0 +1 @@ +.. include:: ../../README.rst \ No newline at end of file From f6a5829fc1ccf6ddcbbb55d92c7abd3d57551e5e Mon Sep 17 00:00:00 2001 From: mbichoffe Date: Tue, 31 Jul 2018 14:04:49 -0700 Subject: [PATCH 08/20] Clean up source/_rst directory before calling sphinx-apidoc --- Makefile | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/Makefile b/Makefile index 5c16691e68..a72b40be65 100644 --- a/Makefile +++ b/Makefile @@ -30,7 +30,8 @@ docs-install: . venv/bin/activate; pip install twilio sphinx docs: - . venv/bin/activate; sphinx-apidoc -f twilio -o docs/source + -rm -rf source/_rst/* + . venv/bin/activate; sphinx-apidoc -f twilio -o docs/source/_rst cd docs && make clean && make html release: From ced3bf00f505eb48edcc3533d99a676c29cab6f8 Mon Sep 17 00:00:00 2001 From: mbichoffe Date: Tue, 31 Jul 2018 14:06:35 -0700 Subject: [PATCH 09/20] Remove unnecessary commands --- docs/Makefile | 127 ++------------------------------------------------ 1 file changed, 3 insertions(+), 124 deletions(-) diff --git a/docs/Makefile b/docs/Makefile index 83d3ca323d..58f4ba2905 100644 --- a/docs/Makefile +++ b/docs/Makefile @@ -15,141 +15,20 @@ ALLSPHINXOPTS = -d $(BUILDDIR)/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) . # the i18n builder cannot share the environment and doctrees with the others I18NSPHINXOPTS = $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) . -.PHONY: help clean html dirhtml singlehtml pickle json htmlhelp qthelp devhelp epub latex latexpdf text man changes linkcheck doctest gettext +.PHONY: help clean html 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 " latexpdf to make LaTeX files and run them through pdflatex" - @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 " linkcheck to check all external links for integrity" - @echo " doctest to run all doctests embedded in the documentation (if enabled)" + clean: -rm -rf $(BUILDDIR)/* + html: $(SPHINXBUILD) -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html @echo @echo "Build finished. The HTML pages are in $(BUILDDIR)/html." -dirhtml: - $(SPHINXBUILD) -b dirhtml $(ALLSPHINXOPTS) $(BUILDDIR)/dirhtml - @echo - @echo "Build finished. The HTML pages are in $(BUILDDIR)/dirhtml." - -singlehtml: - $(SPHINXBUILD) -b singlehtml $(ALLSPHINXOPTS) $(BUILDDIR)/singlehtml - @echo - @echo "Build finished. The HTML page is in $(BUILDDIR)/singlehtml." - -pickle: - $(SPHINXBUILD) -b pickle $(ALLSPHINXOPTS) $(BUILDDIR)/pickle - @echo - @echo "Build finished; now you can process the pickle files." - -json: - $(SPHINXBUILD) -b json $(ALLSPHINXOPTS) $(BUILDDIR)/json - @echo - @echo "Build finished; now you can process the JSON files." - -htmlhelp: - $(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: - $(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/PythonUtils.qhcp" - @echo "To view the help file:" - @echo "# assistant -collectionFile $(BUILDDIR)/qthelp/PythonUtils.qhc" - -devhelp: - $(SPHINXBUILD) -b devhelp $(ALLSPHINXOPTS) $(BUILDDIR)/devhelp - @echo - @echo "Build finished." - @echo "To view the help file:" - @echo "# mkdir -p $$HOME/.local/share/devhelp/PythonUtils" - @echo "# ln -s $(BUILDDIR)/devhelp $$HOME/.local/share/devhelp/PythonUtils" - @echo "# devhelp" - -epub: - $(SPHINXBUILD) -b epub $(ALLSPHINXOPTS) $(BUILDDIR)/epub - @echo - @echo "Build finished. The epub file is in $(BUILDDIR)/epub." - -latex: - $(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: - $(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." - -text: - $(SPHINXBUILD) -b text $(ALLSPHINXOPTS) $(BUILDDIR)/text - @echo - @echo "Build finished. The text files are in $(BUILDDIR)/text." - -man: - $(SPHINXBUILD) -b man $(ALLSPHINXOPTS) $(BUILDDIR)/man - @echo - @echo "Build finished. The manual pages are in $(BUILDDIR)/man." - -texinfo: - $(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: - $(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: - $(SPHINXBUILD) -b gettext $(I18NSPHINXOPTS) $(BUILDDIR)/locale - @echo - @echo "Build finished. The message catalogs are in $(BUILDDIR)/locale." - -changes: - $(SPHINXBUILD) -b changes $(ALLSPHINXOPTS) $(BUILDDIR)/changes - @echo - @echo "The overview file is in $(BUILDDIR)/changes." - -linkcheck: - $(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: - $(SPHINXBUILD) -b doctest $(ALLSPHINXOPTS) $(BUILDDIR)/doctest - @echo "Testing of doctests in the sources finished, look at the " \ - "results in $(BUILDDIR)/doctest/output.txt." From 0b894b6396af5659ffc3c70b37295d639e12dea4 Mon Sep 17 00:00:00 2001 From: mbichoffe Date: Tue, 31 Jul 2018 14:07:45 -0700 Subject: [PATCH 10/20] Remove twilio lib from doc-install --- Makefile | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Makefile b/Makefile index a72b40be65..d642491ab4 100644 --- a/Makefile +++ b/Makefile @@ -27,7 +27,7 @@ cover: find tests -type d | xargs nosetests --with-coverage --cover-inclusive --cover-erase --cover-package=twilio docs-install: - . venv/bin/activate; pip install twilio sphinx + . venv/bin/activate; pip install sphinx docs: -rm -rf source/_rst/* From c55b271c0f3cdaa8e1f18c3b947da2a708e3d34b Mon Sep 17 00:00:00 2001 From: mbichoffe Date: Tue, 31 Jul 2018 14:09:57 -0700 Subject: [PATCH 11/20] Add twilio relative import --- docs/conf.py | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) diff --git a/docs/conf.py b/docs/conf.py index 2427f024c8..77ee302715 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -6,7 +6,6 @@ # full list see the documentation: # http://www.sphinx-doc.org/en/master/config -from twilio import __version__ # -- Path setup -------------------------------------------------------------- @@ -17,6 +16,10 @@ import os import sys sys.path.insert(0, os.path.join(os.path.abspath('..'), 'twilio')) +sys.path.append('..') +from twilio import __version__ + + # -- Project information ----------------------------------------------------- project = 'twilio-python' From 6b7d9ea512de32a9aad17463dee1d4daba93bf76 Mon Sep 17 00:00:00 2001 From: mbichoffe Date: Tue, 31 Jul 2018 14:13:15 -0700 Subject: [PATCH 12/20] add glob flag and _rst/module directive --- docs/source/index.rst | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/docs/source/index.rst b/docs/source/index.rst index 3fa569e4f4..24a780fb40 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -22,9 +22,10 @@ If you are looking for information on a specific function, class or method, this part of the documentation is for you. .. toctree:: - :maxdepth: 2 + :maxdepth: 1 + :glob: - modules + _rst/modules.rst Indices and tables From b4fb42eeec4b2698f10ee501f62dbc3fa43a3f19 Mon Sep 17 00:00:00 2001 From: mbichoffe Date: Tue, 31 Jul 2018 14:19:25 -0700 Subject: [PATCH 13/20] add _rst directory --- .gitignore | 1 + 1 file changed, 1 insertion(+) diff --git a/.gitignore b/.gitignore index 67a9010c30..0a2f063d81 100644 --- a/.gitignore +++ b/.gitignore @@ -26,6 +26,7 @@ pip-log.txt # sphinx build folder _build build/ +_rst # PyCharm/IntelliJ .idea From 05284fccd08e3e96373cf6eb5969c265dcb2a85e Mon Sep 17 00:00:00 2001 From: mbichoffe Date: Tue, 31 Jul 2018 15:40:36 -0700 Subject: [PATCH 14/20] Update master doc location --- docs/Makefile | 34 ---------------------------------- docs/conf.py | 2 +- 2 files changed, 1 insertion(+), 35 deletions(-) delete mode 100644 docs/Makefile diff --git a/docs/Makefile b/docs/Makefile deleted file mode 100644 index 58f4ba2905..0000000000 --- a/docs/Makefile +++ /dev/null @@ -1,34 +0,0 @@ -# Minimal makefile for Sphinx documentation -# - -# You can set these variables from the command line. -SPHINXOPTS = -SPHINXBUILD = sphinx-build -SPHINXPROJ = twilio-python -SOURCEDIR = source -BUILDDIR = build - -# internal variables -PAPEROPT_a4 = -D latex_paper_size=a4 -PAPEROPT_letter = -D latex_paper_size=letter -ALLSPHINXOPTS = -d $(BUILDDIR)/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) . -# the i18n builder cannot share the environment and doctrees with the others -I18NSPHINXOPTS = $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) . - -.PHONY: help clean html - -help: - @echo "Please use \`make ' where is one of" - @echo " html to make standalone HTML files" - - -clean: - -rm -rf $(BUILDDIR)/* - - -html: - $(SPHINXBUILD) -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html - - @echo - @echo "Build finished. The HTML pages are in $(BUILDDIR)/html." - diff --git a/docs/conf.py b/docs/conf.py index 77ee302715..a18da1baba 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -60,7 +60,7 @@ source_suffix = '.rst' # The master toctree document. -master_doc = 'source/index' +master_doc = 'docs/source/index' # The language for content autogenerated by Sphinx. Refer to documentation # for a list of supported languages. From 615d5ae4e8e186d3bb021e9c058429a186009126 Mon Sep 17 00:00:00 2001 From: mbichoffe Date: Tue, 31 Jul 2018 15:41:37 -0700 Subject: [PATCH 15/20] fiiiine, added all sphinx make commands to this file and removed docs/Makefile --- Makefile | 9 +++++++-- 1 file changed, 7 insertions(+), 2 deletions(-) diff --git a/Makefile b/Makefile index d642491ab4..e1157d0884 100644 --- a/Makefile +++ b/Makefile @@ -27,12 +27,17 @@ cover: find tests -type d | xargs nosetests --with-coverage --cover-inclusive --cover-erase --cover-package=twilio docs-install: - . venv/bin/activate; pip install sphinx + . venv/bin/activate; pip install -U sphinx docs: -rm -rf source/_rst/* + -rm -rf build/* . venv/bin/activate; sphinx-apidoc -f twilio -o docs/source/_rst - cd docs && make clean && make html + . venv/bin/activate; sphinx-build -b html -c ./docs -d docs/build/doctrees . docs/build/html + + @echo + @echo "Build finished. The HTML pages are in build/html." + release: . venv/bin/activate; python setup.py sdist upload From a4cdd87813043884a58712fd4e33612746cc1d04 Mon Sep 17 00:00:00 2001 From: mbichoffe Date: Wed, 1 Aug 2018 09:04:25 -0700 Subject: [PATCH 16/20] address code review comments --- Makefile | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/Makefile b/Makefile index e1157d0884..ba94cc10fb 100644 --- a/Makefile +++ b/Makefile @@ -30,8 +30,8 @@ docs-install: . venv/bin/activate; pip install -U sphinx docs: - -rm -rf source/_rst/* - -rm -rf build/* + -rm -rf docs/source/_rst + -rm -rf docs/build/* . venv/bin/activate; sphinx-apidoc -f twilio -o docs/source/_rst . venv/bin/activate; sphinx-build -b html -c ./docs -d docs/build/doctrees . docs/build/html From d788c3d7d7824f1b34ad593e97473817747e4906 Mon Sep 17 00:00:00 2001 From: mbichoffe Date: Wed, 1 Aug 2018 09:31:07 -0700 Subject: [PATCH 17/20] specify docs directories to ignore --- .gitignore | 7 +++---- 1 file changed, 3 insertions(+), 4 deletions(-) diff --git a/.gitignore b/.gitignore index 0a2f063d81..007268cf24 100644 --- a/.gitignore +++ b/.gitignore @@ -23,10 +23,9 @@ pip-log.txt .DS_Store -# sphinx build folder -_build -build/ -_rst +# sphinx build and rst folder +**/docs/_build +**/docs/source/_rst # PyCharm/IntelliJ .idea From b889bdf4e233ec7c3ec9de887768e35833f76235 Mon Sep 17 00:00:00 2001 From: mbichoffe Date: Wed, 1 Aug 2018 09:31:36 -0700 Subject: [PATCH 18/20] address code review comments --- Makefile | 9 +++------ 1 file changed, 3 insertions(+), 6 deletions(-) diff --git a/Makefile b/Makefile index ba94cc10fb..e04e96a562 100644 --- a/Makefile +++ b/Makefile @@ -27,16 +27,13 @@ cover: find tests -type d | xargs nosetests --with-coverage --cover-inclusive --cover-erase --cover-package=twilio docs-install: - . venv/bin/activate; pip install -U sphinx + . venv/bin/activate; pip install -r tests/requirements.txt docs: -rm -rf docs/source/_rst - -rm -rf docs/build/* + -rm -rf docs/build . venv/bin/activate; sphinx-apidoc -f twilio -o docs/source/_rst - . venv/bin/activate; sphinx-build -b html -c ./docs -d docs/build/doctrees . docs/build/html - - @echo - @echo "Build finished. The HTML pages are in build/html." + . venv/bin/activate; sphinx-build -b html -c ./docs -d docs/build/doctrees . docs/build/html release: From d6c49ea097f960fbd17ee3e2d927373e0a951168 Mon Sep 17 00:00:00 2001 From: mbichoffe Date: Wed, 1 Aug 2018 09:32:08 -0700 Subject: [PATCH 19/20] bump Sphinx version --- tests/requirements.txt | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/tests/requirements.txt b/tests/requirements.txt index 3d13d6baa0..6d674c5821 100644 --- a/tests/requirements.txt +++ b/tests/requirements.txt @@ -1,4 +1,4 @@ -sphinx==1.4.9 +Sphinx==1.7.6 mock==0.8.0 nose coverage From 7a6eb0ea72cdd5729be87e0ee4aa96d58b449616 Mon Sep 17 00:00:00 2001 From: mbichoffe Date: Wed, 1 Aug 2018 10:34:31 -0700 Subject: [PATCH 20/20] address code review comment --- .gitignore | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/.gitignore b/.gitignore index 007268cf24..03c5f7bd79 100644 --- a/.gitignore +++ b/.gitignore @@ -24,8 +24,8 @@ pip-log.txt .DS_Store # sphinx build and rst folder -**/docs/_build -**/docs/source/_rst +docs/_build +docs/source/_rst # PyCharm/IntelliJ .idea