From 52f5fe5e3436fa58fd08f9dab83d6588b3ce78ff Mon Sep 17 00:00:00 2001 From: Jeremy Kubica <104161096+jeremykubica@users.noreply.github.com> Date: Fri, 10 Mar 2023 11:09:25 -0500 Subject: [PATCH 1/5] Refactor the documentation directory --- .gitignore | 3 ++- python-project-template/docs/Makefile | 20 +++++++++++++++++++ .../docs/{ => source}/conf.py.jinja | 4 ++-- .../docs/{ => source}/index.rst.jinja | 0 4 files changed, 24 insertions(+), 3 deletions(-) create mode 100644 python-project-template/docs/Makefile rename python-project-template/docs/{ => source}/conf.py.jinja (94%) rename python-project-template/docs/{ => source}/index.rst.jinja (100%) diff --git a/.gitignore b/.gitignore index f05b088c..c52b67cc 100644 --- a/.gitignore +++ b/.gitignore @@ -131,4 +131,5 @@ dmypy.json .pyre/ # vscode -.vscode/ \ No newline at end of file +.vscode/ +.DS_Store diff --git a/python-project-template/docs/Makefile b/python-project-template/docs/Makefile new file mode 100644 index 00000000..d0c3cbf1 --- /dev/null +++ b/python-project-template/docs/Makefile @@ -0,0 +1,20 @@ +# Minimal makefile for Sphinx documentation +# + +# You can set these variables from the command line, and also +# from the environment for the first two. +SPHINXOPTS ?= +SPHINXBUILD ?= sphinx-build +SOURCEDIR = source +BUILDDIR = build + +# Put it first so that "make" without argument is like "make help". +help: + @$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) + +.PHONY: help Makefile + +# Catch-all target: route all unknown targets to Sphinx using the new +# "make mode" option. $(O) is meant as a shortcut for $(SPHINXOPTS). +%: Makefile + @$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) diff --git a/python-project-template/docs/conf.py.jinja b/python-project-template/docs/source/conf.py.jinja similarity index 94% rename from python-project-template/docs/conf.py.jinja rename to python-project-template/docs/source/conf.py.jinja index c728db3b..8f99da81 100644 --- a/python-project-template/docs/conf.py.jinja +++ b/python-project-template/docs/source/conf.py.jinja @@ -11,7 +11,7 @@ import autoapi from importlib.metadata import version # Define path to the code to be documented **relative to where conf.py (this file) is kept** -sys.path.insert(0, os.path.abspath('../src/')) +sys.path.insert(0, os.path.abspath('../../src/')) # -- Project information ----------------------------------------------------- # https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information @@ -38,7 +38,7 @@ html_show_sourcelink = False # Remove 'view source code' from top of page (for add_module_names = False # Remove namespaces from class/method signatures autoapi_type = "python" -autoapi_dirs = ["../src"] +autoapi_dirs = ["../../src"] autoapi_add_toc_tree_entry = False autoapi_member_order = "bysource" diff --git a/python-project-template/docs/index.rst.jinja b/python-project-template/docs/source/index.rst.jinja similarity index 100% rename from python-project-template/docs/index.rst.jinja rename to python-project-template/docs/source/index.rst.jinja From 0b516ac51b65afbc8c58300ba098b85b08974339 Mon Sep 17 00:00:00 2001 From: Jeremy Kubica <104161096+jeremykubica@users.noreply.github.com> Date: Fri, 10 Mar 2023 11:14:49 -0500 Subject: [PATCH 2/5] Restructure the doc directory again --- python-project-template/docs/Makefile | 2 +- python-project-template/docs/{source => }/conf.py.jinja | 0 python-project-template/docs/{source => }/index.rst.jinja | 0 3 files changed, 1 insertion(+), 1 deletion(-) rename python-project-template/docs/{source => }/conf.py.jinja (100%) rename python-project-template/docs/{source => }/index.rst.jinja (100%) diff --git a/python-project-template/docs/Makefile b/python-project-template/docs/Makefile index d0c3cbf1..ed880990 100644 --- a/python-project-template/docs/Makefile +++ b/python-project-template/docs/Makefile @@ -5,7 +5,7 @@ # from the environment for the first two. SPHINXOPTS ?= SPHINXBUILD ?= sphinx-build -SOURCEDIR = source +SOURCEDIR = . BUILDDIR = build # Put it first so that "make" without argument is like "make help". diff --git a/python-project-template/docs/source/conf.py.jinja b/python-project-template/docs/conf.py.jinja similarity index 100% rename from python-project-template/docs/source/conf.py.jinja rename to python-project-template/docs/conf.py.jinja diff --git a/python-project-template/docs/source/index.rst.jinja b/python-project-template/docs/index.rst.jinja similarity index 100% rename from python-project-template/docs/source/index.rst.jinja rename to python-project-template/docs/index.rst.jinja From 09fc3a28af6bf388fbc7bb18fd7860dd41b5f129 Mon Sep 17 00:00:00 2001 From: Jeremy Kubica <104161096+jeremykubica@users.noreply.github.com> Date: Fri, 10 Mar 2023 11:27:04 -0500 Subject: [PATCH 3/5] Add readthedocs options to the makefile --- python-project-template/docs/Makefile | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/python-project-template/docs/Makefile b/python-project-template/docs/Makefile index ed880990..d7e04837 100644 --- a/python-project-template/docs/Makefile +++ b/python-project-template/docs/Makefile @@ -3,10 +3,10 @@ # You can set these variables from the command line, and also # from the environment for the first two. -SPHINXOPTS ?= +SPHINXOPTS ?= -T -E -d _build/doctrees -D language=en SPHINXBUILD ?= sphinx-build SOURCEDIR = . -BUILDDIR = build +BUILDDIR = ../_readthedocs/ # Put it first so that "make" without argument is like "make help". help: @@ -18,3 +18,4 @@ help: # "make mode" option. $(O) is meant as a shortcut for $(SPHINXOPTS). %: Makefile @$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) + From 3df69680f8f5a342cd050600c98157a55092f9bd Mon Sep 17 00:00:00 2001 From: Jeremy Kubica <104161096+jeremykubica@users.noreply.github.com> Date: Fri, 10 Mar 2023 11:30:43 -0500 Subject: [PATCH 4/5] Move the source files into a source directory --- python-project-template/docs/Makefile | 2 +- python-project-template/docs/{ => source}/conf.py.jinja | 0 python-project-template/docs/{ => source}/index.rst.jinja | 0 3 files changed, 1 insertion(+), 1 deletion(-) rename python-project-template/docs/{ => source}/conf.py.jinja (100%) rename python-project-template/docs/{ => source}/index.rst.jinja (100%) diff --git a/python-project-template/docs/Makefile b/python-project-template/docs/Makefile index d7e04837..8aa4842c 100644 --- a/python-project-template/docs/Makefile +++ b/python-project-template/docs/Makefile @@ -5,7 +5,7 @@ # from the environment for the first two. SPHINXOPTS ?= -T -E -d _build/doctrees -D language=en SPHINXBUILD ?= sphinx-build -SOURCEDIR = . +SOURCEDIR = source BUILDDIR = ../_readthedocs/ # Put it first so that "make" without argument is like "make help". diff --git a/python-project-template/docs/conf.py.jinja b/python-project-template/docs/source/conf.py.jinja similarity index 100% rename from python-project-template/docs/conf.py.jinja rename to python-project-template/docs/source/conf.py.jinja diff --git a/python-project-template/docs/index.rst.jinja b/python-project-template/docs/source/index.rst.jinja similarity index 100% rename from python-project-template/docs/index.rst.jinja rename to python-project-template/docs/source/index.rst.jinja From cf7435c2554aec0a71c0d5863a7b18f1303d8462 Mon Sep 17 00:00:00 2001 From: Jeremy Kubica <104161096+jeremykubica@users.noreply.github.com> Date: Fri, 10 Mar 2023 11:42:00 -0500 Subject: [PATCH 5/5] Get rid of the docs/source directory --- python-project-template/docs/Makefile | 2 +- python-project-template/docs/{source => }/conf.py.jinja | 4 ++-- python-project-template/docs/{source => }/index.rst.jinja | 0 3 files changed, 3 insertions(+), 3 deletions(-) rename python-project-template/docs/{source => }/conf.py.jinja (94%) rename python-project-template/docs/{source => }/index.rst.jinja (100%) diff --git a/python-project-template/docs/Makefile b/python-project-template/docs/Makefile index 8aa4842c..d7e04837 100644 --- a/python-project-template/docs/Makefile +++ b/python-project-template/docs/Makefile @@ -5,7 +5,7 @@ # from the environment for the first two. SPHINXOPTS ?= -T -E -d _build/doctrees -D language=en SPHINXBUILD ?= sphinx-build -SOURCEDIR = source +SOURCEDIR = . BUILDDIR = ../_readthedocs/ # Put it first so that "make" without argument is like "make help". diff --git a/python-project-template/docs/source/conf.py.jinja b/python-project-template/docs/conf.py.jinja similarity index 94% rename from python-project-template/docs/source/conf.py.jinja rename to python-project-template/docs/conf.py.jinja index 8f99da81..c728db3b 100644 --- a/python-project-template/docs/source/conf.py.jinja +++ b/python-project-template/docs/conf.py.jinja @@ -11,7 +11,7 @@ import autoapi from importlib.metadata import version # Define path to the code to be documented **relative to where conf.py (this file) is kept** -sys.path.insert(0, os.path.abspath('../../src/')) +sys.path.insert(0, os.path.abspath('../src/')) # -- Project information ----------------------------------------------------- # https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information @@ -38,7 +38,7 @@ html_show_sourcelink = False # Remove 'view source code' from top of page (for add_module_names = False # Remove namespaces from class/method signatures autoapi_type = "python" -autoapi_dirs = ["../../src"] +autoapi_dirs = ["../src"] autoapi_add_toc_tree_entry = False autoapi_member_order = "bysource" diff --git a/python-project-template/docs/source/index.rst.jinja b/python-project-template/docs/index.rst.jinja similarity index 100% rename from python-project-template/docs/source/index.rst.jinja rename to python-project-template/docs/index.rst.jinja