diff --git a/.gitignore b/.gitignore index 02d4739..1b06f9b 100644 --- a/.gitignore +++ b/.gitignore @@ -5,3 +5,4 @@ bin/* Pipfile.lock html latex +xml diff --git a/.readthedocs.yaml b/.readthedocs.yaml new file mode 100644 index 0000000..3445344 --- /dev/null +++ b/.readthedocs.yaml @@ -0,0 +1,4 @@ +version: 1 + +conda: + environment: docs/conda.yml diff --git a/.woodpecker.yml b/.woodpecker.yml index b8456bb..ffb6941 100644 --- a/.woodpecker.yml +++ b/.woodpecker.yml @@ -17,3 +17,7 @@ pipeline: image: python - pip install -U platformio - pio check -e esp8266 -e esp32 --skip-packages --severity medium --severity high --pattern 'src' --pattern 'lib/Figments' --fail-on-defect high + docs: + image: python + - pip install -U breathe sphinx + - cd docs && sphinx diff --git a/Doxygen b/Doxyfile similarity index 99% rename from Doxygen rename to Doxyfile index 8640f80..32513d4 100644 --- a/Doxygen +++ b/Doxyfile @@ -2094,7 +2094,7 @@ MAN_LINKS = NO # captures the structure of the code including all documentation. # The default value is: NO. -GENERATE_XML = NO +GENERATE_XML = YES # The XML_OUTPUT tag is used to specify where the XML pages will be put. If a # relative path is entered the value of OUTPUT_DIRECTORY will be put in front of diff --git a/Pipfile b/Pipfile index ec8268b..9e9361d 100644 --- a/Pipfile +++ b/Pipfile @@ -5,6 +5,8 @@ name = "pypi" [packages] platformio = "*" +sphinx = "*" +breathe = "*" [dev-packages] diff --git a/docs/.gitignore b/docs/.gitignore new file mode 100644 index 0000000..e35d885 --- /dev/null +++ b/docs/.gitignore @@ -0,0 +1 @@ +_build diff --git a/docs/Makefile b/docs/Makefile new file mode 100644 index 0000000..d4bb2cb --- /dev/null +++ b/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 = . +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/docs/_static/.gitkeep b/docs/_static/.gitkeep new file mode 100644 index 0000000..e69de29 diff --git a/docs/_templates/.gitkeep b/docs/_templates/.gitkeep new file mode 100644 index 0000000..e69de29 diff --git a/docs/conda.yml b/docs/conda.yml new file mode 100644 index 0000000..357890c --- /dev/null +++ b/docs/conda.yml @@ -0,0 +1,7 @@ +name: renderbug-docs + +channels: + - conda-forge + +dependencies: + - breathe diff --git a/docs/conf.py b/docs/conf.py new file mode 100644 index 0000000..84acfda --- /dev/null +++ b/docs/conf.py @@ -0,0 +1,50 @@ +# Configuration file for the Sphinx documentation builder. +# +# For the full list of built-in configuration values, see the documentation: +# https://www.sphinx-doc.org/en/master/usage/configuration.html + +# -- Project information ----------------------------------------------------- +# https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information + +project = 'Renderbug' +copyright = '2023, Victoria Fierce' +author = 'Victoria Fierce' + +# -- General configuration --------------------------------------------------- +# https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration + +extensions = ['breathe'] + +breathe_projects = {"renderbug": "../xml"} + +breathe_default_project = "renderbug" + +templates_path = ['_templates'] +exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store'] + + + +# -- Options for HTML output ------------------------------------------------- +# https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output + +html_theme = 'alabaster' +html_static_path = ['_static'] + +import subprocess, sys, os + +def generate_doxygen_xml(app): + read_the_docs_build = os.environ.get('READTHEDOCS', None) == 'True' + + if read_the_docs_build: + try: + retcode = subprocess.call("cd ../; doxygen", shell=True) + if retcode < 0: + sys.stderr.write("doxygen terminated by signal %s" % (-retcode)) + except OSError as e: + sys.stderr.write("doxygen execution failed: %s" % e) + + +def setup(app): + + # Add hook for building doxygen xml when needed + app.connect("builder-inited", generate_doxygen_xml) diff --git a/docs/index.rst b/docs/index.rst new file mode 100644 index 0000000..865642c --- /dev/null +++ b/docs/index.rst @@ -0,0 +1,24 @@ +.. Renderbug documentation master file, created by + sphinx-quickstart on Sat Mar 4 13:04:23 2023. + You can adapt this file completely to your liking, but it should at least + contain the root `toctree` directive. + +Welcome to Renderbug's documentation! +===================================== + +.. toctree:: + :maxdepth: 2 + :caption: Contents: + + +API Documentation +================= + +.. doxygenindex:: + +Indices and tables +================== + +* :ref:`genindex` +* :ref:`modindex` +* :ref:`search`