Fix Sphinx-Click Issues on Readthedocs.org (#85)

You-Cyuan Jhang · web-flow · commit 97684efca862 · 2020-09-09T10:56:11.000-07:00
* Fix sphinx click extension

* test trigger read the docs

* Fix missing click doc

* update readathedocs to use requirements.txt file

* add dins dep
diff --git a/.readthedocs.yml b/.readthedocs.yml
@@ -1,11 +1,12 @@
 # .readthedocs.yml
 version: 2
-sphinx:
-  configuration: docs/source/conf.py
+formats: all
 python:
   version: 3.7
   install:
+    - requirements: docs/requirements.txt
     - method: pip
       path: .
-      extra_requirements:
-        - docs
+sphinx:
+  builder: html
+  configuration: docs/source/conf.py
diff --git a/docs/Makefile b/docs/Makefile
@@ -12,11 +12,11 @@ help:
 
 clean:
 	rm -rf $(BUILDDIR)
-	find $(SOURCEDIR) -name "*.rst" | grep -v index | xargs rm -f
 
 apidoc:
-	sphinx-apidoc -f --templatedir=$(TEMPLATEDIR) -o $(SOURCEDIR) -d 2 ../datasetinsights/ ../datasetinsights/stats/visualization ../datasetinsights/dashboard.py ../datasetinsights/datasets/protos
-html: apidoc
+	sphinx-apidoc --templatedir=$(TEMPLATEDIR) -o $(SOURCEDIR) -d 2 ../datasetinsights/ ../datasetinsights/stats/visualization ../datasetinsights/dashboard.py ../datasetinsights/datasets/protos
+
+html:
 	sphinx-build -b html $(SOURCEDIR) $(BUILDDIR)/html
 	@echo
 	@echo "Build finished. The HTML doumentation pages are in $(BUILDDIR)/html."
diff --git a/docs/README.md b/docs/README.md
@@ -4,27 +4,34 @@ Building documentation
 Run the following commands from `docs` directory.
 
 Automatic generate of Sphinx sources using [sphinx-apidoc](https://www.sphinx-doc.org/en/master/man/sphinx-apidoc.html)
+
 ```bash
 make apidoc
 ```
 
-Build html files
+This command only applies to newly created modules. It will not update modules that already exist. You will have to modify `docs/datasetinsighs.module_name` manually.
+
+To build html files, run
 
 ```bash
 make html
 ```
 
 You can browse the documentation by opening `build/html/index.html` file directly in any web browser.
 
-Cleanup build files
+Cleanup build html files
+
 ```bash
 make clean
 ```
 
-
 Known issues
 ------------
 
-When using commonmark to convert markdown files to rst files, links to headers cannot have `_` or `.`.
-If the header has either of those characters, they should be replaced by dashes `-`.
-e.g. if you have a header `#### annotation_definitions.json` in the markdown file, to link to that header the markdown needs to be `[click link](#annotation-definitions-json)`
+1. Some of the documents are written in markdown format. We use [recommonmark](https://github.com/readthedocs/recommonmark) to generate documentations. It uses [CommonMark](http://commonmark.org/) to convert markdown files to rst files. Due to it's limitation, links to headers cannot have `_` or `.`. If the header has either of those characters, they should be replaced by dashes `-`. e.g. if you have a header `#### annotation_definitions.json` in the markdown file, to link to that header the markdown needs to be `[click link](#annotation-definitions-json)`
+
+2. `Readthedocs.org` does not currently support [poetry](https://python-poetry.org/) officially. Until then, we have to manually generated a `docs/requirements.txt` file when new requirements is added to the repo. This file can be generated using command:
+
+```bash
+poetry export --dev --without-hashes -f requirements.txt > docs/requirements.txt
+```
diff --git a/docs/requirements.txt b/docs/requirements.txt
@@ -0,0 +1,190 @@
+absl-py==0.10.0
+alabaster==0.7.12
+appdirs==1.4.4
+appnope==0.1.0; python_version >= "3.3" and sys_platform == "darwin" or platform_system == "Darwin"
+argon2-cffi==20.1.0
+astunparse==1.6.3
+atomicwrites==1.4.0; sys_platform == "win32"
+attrs==20.2.0
+babel==2.8.0
+backcall==0.2.0; python_version >= "3.3"
+black==19.10b0
+bleach==3.1.5
+bokeh==2.2.1
+brotli==1.0.9
+cachetools==4.1.1
+certifi==2020.6.20
+cffi==1.14.2
+chardet==3.0.4
+click==7.1.2
+cloudpickle==1.6.0
+codetiming==1.2.0
+colorama==0.4.3; python_version >= "3.3" and sys_platform == "win32" or sys_platform == "win32"
+commonmark==0.9.1
+coverage==5.2.1
+cycler==0.10.0
+cython==0.29.21
+dash==1.12.0
+dash-core-components==1.10.0
+dash-html-components==1.0.3
+dash-renderer==1.4.1
+dash-table==4.7.0
+dask==2.25.0
+decorator==4.4.2; python_version >= "3.3"
+defusedxml==0.6.0
+deprecated==1.2.10
+descartes==1.1.0
+distributed==2.25.0
+docutils==0.16
+entrypoints==0.3
+flake8==3.8.3
+flask==1.1.2
+flask-compress==1.5.0
+fsspec==0.8.0
+future==0.18.2
+gast==0.3.3
+google-api-core==1.22.2
+google-auth==1.21.1
+google-auth-oauthlib==0.4.1
+google-cloud-core==1.4.1
+google-cloud-storage==1.28.1
+google-pasta==0.2.0
+google-resumable-media==0.5.1
+googleapis-common-protos==1.52.0
+grpcio==1.31.0
+h5py==2.10.0
+heapdict==1.0.1
+idna==2.10
+imagesize==1.2.0
+importlib-metadata==1.7.0; python_version < "3.8"
+ipykernel==5.3.4
+ipython==7.18.1
+ipython-genutils==0.2.0
+ipywidgets==7.5.1
+isort==4.3.21
+itsdangerous==1.1.0
+jedi==0.17.2; python_version >= "3.3"
+jinja2==2.11.2
+joblib==0.16.0
+jsonschema==3.2.0
+jupyter==1.0.0
+jupyter-client==6.1.7
+jupyter-console==6.2.0
+jupyter-core==4.6.3
+keras-preprocessing==1.1.2
+kfp==1.0.0
+kfp-server-api==1.0.0
+kiwisolver==1.2.0
+kornia==0.1.4.post2
+kubernetes==11.0.0
+locket==0.2.0
+markdown==3.2.2
+markupsafe==1.1.1
+matplotlib==3.3.1
+mccabe==0.6.1
+mistune==0.8.4
+more-itertools==8.5.0
+msgpack==1.0.0
+nbconvert==5.6.1
+nbformat==5.0.7
+notebook==6.1.4
+numpy==1.17.5
+nuscenes-devkit==1.0.2
+oauthlib==3.1.0
+opencv-python==4.4.0.42
+opt-einsum==3.3.0
+packaging==20.4
+pandas==1.1.2
+pandocfilters==1.4.2
+parso==0.7.1; python_version >= "3.3"
+partd==1.1.0
+pathspec==0.8.0
+pbr==5.5.0
+pexpect==4.8.0; python_version >= "3.3" and sys_platform != "win32"
+pickleshare==0.7.5; python_version >= "3.3"
+pillow==7.2.0
+plotly==4.9.0
+pluggy==0.13.1
+prometheus-client==0.8.0
+prompt-toolkit==3.0.7
+protobuf==3.13.0
+psutil==5.7.2
+ptyprocess==0.6.0; python_version >= "3.3" and sys_platform != "win32" or os_name != "nt"
+py==1.9.0
+pyasn1==0.4.8
+pyasn1-modules==0.2.8
+pycocotools==2.0.2
+pycodestyle==2.6.0
+pycparser==2.20
+pyflakes==2.2.0
+pygments==2.6.1
+pyparsing==2.4.7
+pyquaternion==0.9.5
+pyrsistent==0.17.0
+pytest==5.4.3
+pytest-cov==2.10.1
+python-dateutil==2.8.1
+pytorch-ignite==0.3.0
+pytz==2020.1
+pywin32==228; sys_platform == "win32"
+pywinpty==0.5.7; os_name == "nt"
+pyyaml==5.3.1
+pyzmq==19.0.2
+qtconsole==4.7.7
+qtpy==1.9.0
+recommonmark==0.6.0
+regex==2020.7.14
+requests==2.24.0
+requests-oauthlib==1.3.0
+requests-toolbelt==0.9.1
+responses==0.10.16
+retrying==1.3.3
+rsa==4.6; python_version >= "3.5"
+scikit-learn==0.23.2
+scipy==1.4.1
+send2trash==1.5.0
+shapely==1.7.1
+six==1.15.0
+snowballstemmer==2.0.0
+sortedcontainers==2.2.2
+sphinx==3.2.1
+sphinx-click==2.5.0
+sphinx-rtd-theme==0.5.0
+sphinxcontrib-applehelp==1.0.2
+sphinxcontrib-devhelp==1.0.2
+sphinxcontrib-htmlhelp==1.0.3
+sphinxcontrib-jsmath==1.0.1
+sphinxcontrib-qthelp==1.0.3
+sphinxcontrib-serializinghtml==1.1.4
+strip-hints==0.1.9
+tabulate==0.8.7
+tblib==1.7.0
+tensorboard==2.3.0
+tensorboard-plugin-wit==1.7.0
+tensorboardx==2.1
+tensorflow==2.3.0
+tensorflow-estimator==2.3.0
+termcolor==1.1.0
+terminado==0.8.3
+testpath==0.4.4
+threadpoolctl==2.1.0
+toml==0.10.1
+toolz==0.10.0
+torch==1.4.0
+torchvision==0.5.0
+tornado==6.0.4
+tqdm==4.48.2
+traitlets==5.0.4
+typed-ast==1.4.1
+typing-extensions==3.7.4.3
+urllib3==1.25.10
+wcwidth==0.2.5
+webencodings==0.5.1
+websocket-client==0.57.0
+werkzeug==1.0.1
+wheel==0.35.1
+widgetsnbextension==3.5.1
+wrapt==1.12.1
+yacs==0.1.8
+zict==2.0.0
+zipp==3.1.0; python_version < "3.8"
diff --git a/docs/source/conf.py b/docs/source/conf.py
@@ -34,7 +34,7 @@
     "sphinx.ext.autosectionlabel",
     "sphinx_rtd_theme",
     "sphinx.ext.napoleon",
-    "sphinx_click.ext",
+    "sphinx_click",
 ]
 
 source_suffix = {
diff --git a/docs/source/datasetinsights.commands.rst b/docs/source/datasetinsights.commands.rst
@@ -5,6 +5,12 @@ datasetinsights.commands
 datasetinsights.commands.download
 ---------------------------------
 
+
+.. click:: datasetinsights.commands.download:cli
+   :prog: datasetinsights download
+   :show-nested:
+
+
 .. automodule:: datasetinsights.commands.download
    :members:
    :undoc-members:
@@ -13,6 +19,12 @@ datasetinsights.commands.download
 datasetinsights.commands.evaluate
 ---------------------------------
 
+
+.. click:: datasetinsights.commands.evaluate:cli
+   :prog: datasetinsights evaluate
+   :show-nested:
+
+
 .. automodule:: datasetinsights.commands.evaluate
    :members:
    :undoc-members:
@@ -21,6 +33,12 @@ datasetinsights.commands.evaluate
 datasetinsights.commands.train
 ------------------------------
 
+
+.. click:: datasetinsights.commands.train:cli
+   :prog: datasetinsights train
+   :show-nested:
+
+
 .. automodule:: datasetinsights.commands.train
    :members:
    :undoc-members:
diff --git a/docs/source/index.rst b/docs/source/index.rst
@@ -92,6 +92,7 @@ Contents
 
    Synthetic_Dataset_Schema
 
+
 Indices and tables
 ==================
 
diff --git a/poetry.lock b/poetry.lock
diff --git a/pyproject.toml b/pyproject.toml

Original file line number	Diff line number	Diff line change
`@@ -34,7 +34,7 @@`
`34`	`34`	`"sphinx.ext.autosectionlabel",`
`35`	`35`	`"sphinx_rtd_theme",`
`36`	`36`	`"sphinx.ext.napoleon",`
`37`		`- "sphinx_click.ext",`
	`37`	`+ "sphinx_click",`
`38`	`38`	`]`
`39`	`39`
`40`	`40`	`source_suffix = {`