Merge pull request #94 from argtable/arg-92

docs: use new sphinx file structure
argtable · May 3, 2024 · 14c244a · 14c244a
2 parents 7e49a73 + 158a626
commit 14c244a
Show file tree

Hide file tree

Showing 25 changed files with 817 additions and 296 deletions.
diff --git a/.gitignore b/.gitignore
@@ -6,6 +6,9 @@ dist/
 .archive/
 .tags/
 .misc/
+.py*/
+docs/source/xml/
+docs/build/
 
 # Ignore JetBrains and Eclipse IDE metadata and default build directories
 .vscode/

diff --git a/Makefile b/Makefile
@@ -41,9 +41,11 @@ MKINDEX  = makeindex
 PRINTF   = printf
 GIT      = git
 
-BUILD_DIR   = build
-ARCHIVE_DIR = .archive
-TAGS_DIR    = .tags
+BUILD_DIR       = build
+DOXYGEN_XML_DIR = docs/source/xml
+DOCS_BUILD_DIR  = docs/build
+ARCHIVE_DIR     = .archive
+TAGS_DIR        = .tags
 
 MAKEFILE_PATH := $(abspath $(lastword $(MAKEFILE_LIST)))
 MAKEFILE_DIR := $(abspath $(dir $(MAKEFILE_PATH)))
@@ -112,6 +114,8 @@ taglist:
 cleanall:
 	@$(PRINTF) "Clean the distribution package and temp files...\n"
 	@$(RM) $(BUILD_DIR)
+	@$(RM) $(DOXYGEN_XML_DIR)
+	@$(RM) $(DOCS_BUILD_DIR)
 
 
 .PHONY: githead

diff --git a/README.md b/README.md
@@ -190,7 +190,7 @@ amalgamation distribution under the build directory.
 Documentation
 -------------
 
-To learn how to use the Argtable3 API, you can see the documentation on the web
+To learn how to use the Argtable3 API, you can read the documentation on the web
 site, study examples in the `examples` directory, or even check the unit tests
 in the `tests` directory.
 
@@ -199,24 +199,40 @@ tools:
 
 * [Sphinx](https://www.sphinx-doc.org): A documentation generator based on the
   reStructuredText markup format.
-* [Read the Docs Sphinx Theme](https://sphinx-rtd-theme.readthedocs.io): A
-  Sphinx theme designed to look modern and be mobile-friendly.
+* [Furo Theme](https://pradyunsg.me/furo/quickstart/): A Sphinx theme designed
+  to look modern and be mobile-friendly.
 * [Breathe](https://breathe.readthedocs.io): A bridge between the Sphinx and
   Doxygen documentation systems.
 * [Doxygen](http://www.doxygen.nl/): A documentation generator for C/C++
   sources.
+* [MyST Parser](https://myst-parser.readthedocs.io): A Sphinx extension to parse
+  MyST, a rich and extensible flavour of Markdown for authoring technical and
+  scientific documentation.
 
-Go to the `docs` directory and run the `doxygen` command to generate Doxygen XML
-output, which will be saved in the `docs/xml` directory:
+Except Doxygen, all the document generation tools are Python-based, so you can
+install the tools in a Python virtual environment:
 
 ```
-$ doxygen
+$ python --version
+Python 3.11.5
+
+$ python -m venv .py311
+$ .py311\Scripts\activate.bat
+
+(.py311) $ pip install --upgrade sphinx
+(.py311) $ pip install --upgrade furo
+(.py311) $ pip install --upgrade breathe
+(.py311) $ pip install --upgrade myst-parser
 ```
 
-Run the `make` batch script and you will see the documentation in the
-`docs/_build/html` directory.
+After installing the tools, go to the `docs` directory and run the `doxygen`
+command to generate the Doxygen XML output, which should be generated in the
+`docs/source/xml` directory. Finally, run `make html` to generate the
+documentation in the `docs/build/html` directory.
 
 ```
+$ cd docs
+$ doxygen
 $ make html
 ```
 

diff --git a/docs/Doxyfile b/docs/Doxyfile
@@ -1,5 +1,5 @@
 PROJECT_NAME      = "argtable"
-XML_OUTPUT        = xml
+XML_OUTPUT        = source/xml
 INPUT             = ../src
 GENERATE_LATEX    = NO
 GENERATE_MAN      = NO

diff --git a/docs/Makefile b/docs/Makefile
@@ -5,8 +5,8 @@
 # from the environment for the first two.
 SPHINXOPTS    ?=
 SPHINXBUILD   ?= sphinx-build
-SOURCEDIR     = .
-BUILDDIR      = _build
+SOURCEDIR     = source
+BUILDDIR      = build
 
 # Put it first so that "make" without argument is like "make help".
 help:

diff --git a/docs/_static/custom.css b/docs/_static/custom.css
diff --git a/docs/conf.py b/docs/conf.py
diff --git a/docs/index.rst b/docs/index.rst