Auto generate docs with sphinx #442

mbichoffe · 2018-07-30T23:41:39Z

Replace pdoc with Sphinx to auto-generate API reference.

…ries and 'make docs' to run sphinx-apidoc

ekarson · 2018-07-30T23:46:47Z

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


does this install twilio in the virtualenv? is that necessary?

I've imported __version__ from the twilio module on docs/config.py . Is there a way to grab the current API version that doesn't require installing twilio?

You don't want the current API version -- you want the next API version (the one you're building the docs for). You already have the source for that in the virtualenv.

ekarson · 2018-07-30T23:50:51Z

docs/Makefile

@@ -0,0 +1,155 @@
+# Minimal makefile for Sphinx documentation


if we're using sphinx-apidoc to generate the docs, do we need this Makefile?

The sphinx-apidoc generates the .rst files, that are used in this Makefile when we call make html (look at line 34 of the Makefile above).

I see. I think it will be easier to understand if you call rm docs and sphinx-build directly from the existing Makefile, rather than adding a second one.

(You might as well remove the entire docs directory, rather than just build, right?)

I've moved all the autogenerated .rst files to source/_rst. Now the directory is cleaned up every time new docs are generated (also added to .gitignore). This addresses your concern about deprecated modules (even though the rst files are just directives, so a new html wouldn't be created but the deprecated .rst file would stay there).

I would prefer to keep the two Makefiles, if you don't have a strong motivation behind merging them. Sphix's internal variables would make twilio-python/Makefile too crowded.

ekarson · 2018-07-31T15:15:31Z

docs/Makefile

@@ -0,0 +1,155 @@
+# Minimal makefile for Sphinx documentation


I see. I think it will be easier to understand if you call rm docs and sphinx-build directly from the existing Makefile, rather than adding a second one.

(You might as well remove the entire docs directory, rather than just build, right?)

ekarson · 2018-07-31T15:23:12Z

docs/Makefile

+	-rm -rf $(BUILDDIR)/*
+
+html:
+	$(SPHINXBUILD) -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html


this is going to put the docs into docs/build/html, right? So I think you'll either need to open a PR against librarian to look there instead of in docs, or you'll need to change the output directory to match what librarian expects.

…/Makefile

ekarson · 2018-07-31T22:46:41Z

Makefile

@@ -27,11 +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 twilio sphinx
+	. venv/bin/activate; pip install -U sphinx


Maybe better to use pip install -r tests/requirements.txt? It looks like we already require sphinx 1.4.9 there.

ekarson · 2018-07-31T22:56:02Z

.gitignore

@@ -26,6 +26,7 @@ pip-log.txt
 # sphinx build folder


I'm confused about the directory structure -- shouldn't these be located underneath docs/?

ekarson · 2018-07-31T22:57:11Z

Makefile

+	-rm -rf source/_rst/*
+	-rm -rf 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


how does sphinx-build know where to find index.rst?

It's on conf.py and the -c flag indicates where the conf file lives

ekarson · 2018-07-31T22:57:40Z

Makefile

+	. 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


none of the other make targets have an output message like this, so I would drop it here too

ekarson · 2018-07-31T22:59:05Z

Makefile


 docs:
-	. venv/bin/activate; sphinx-apidoc -f twilio -o docs/source
-	cd docs && make clean && make html
+	-rm -rf source/_rst/*


shouldn't these paths have a docs/ prefix?

Also, if the directory must exist in order for sphinx to work, I think you'll need to add it yourself. If sphinx is OK with a nonexistent directory, then you can delete the directory itself instead of its contents.

Yes, Sphinx is ok with non-existent directory, and it creates one if it doesn't exist. And I will add the docs/ prefix

ekarson · 2018-08-01T16:44:39Z

.gitignore

-build/
-_rst
+# sphinx build and rst folder
+**/docs/_build


I don't think we need the **, do we? docs is a top-level directory

The double asterisks match patterns anywhere in the directory (even if it is top level)

mbichoffe added 7 commits July 30, 2018 14:52

Change 'make docs-install' command to install Sphinx and Twilio libra…

53437e4

…ries and 'make docs' to run sphinx-apidoc

update gitignore to ignore build directories

200900d

Add docs directory and Makefile

98e6e19

add config file

6808032

add sidebar template;

fab86d0

adds index directive

4061c61

adds readme to autogenerated docs

a7f92bd

mbichoffe requested review from cjcodes, yannieyip and ekarson July 30, 2018 23:42

ekarson reviewed Jul 30, 2018

View reviewed changes

ekarson suggested changes Jul 31, 2018

View reviewed changes

mbichoffe added 8 commits July 31, 2018 14:04

Clean up source/_rst directory before calling sphinx-apidoc

f6a5829

Remove unnecessary commands

ced3bf0

Remove twilio lib from doc-install

0b894b6

Add twilio relative import

c55b271

add glob flag and _rst/module directive

6b7d9ea

add _rst directory

b4fb42e

Update master doc location

05284fc

fiiiine, added all sphinx make commands to this file and removed docs…

615d5ae

…/Makefile

ekarson reviewed Jul 31, 2018

View reviewed changes

mbichoffe added 4 commits August 1, 2018 09:04

address code review comments

a4cdd87

specify docs directories to ignore

d788c3d

address code review comments

b889bdf

bump Sphinx version

d6c49ea

ekarson suggested changes Aug 1, 2018

View reviewed changes

address code review comment

7a6eb0e

ekarson approved these changes Aug 1, 2018

View reviewed changes

mbichoffe merged commit 7d0bf3f into master Aug 3, 2018

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

Auto generate docs with sphinx #442

Auto generate docs with sphinx #442

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

		@@ -0,0 +1,155 @@
		# Minimal makefile for Sphinx documentation

Auto generate docs with sphinx #442

Auto generate docs with sphinx #442

Uh oh!

Conversation

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!