From 17393071c2ffae76a6412e24b26e05188fd43eed Mon Sep 17 00:00:00 2001 From: Henry Borchers Date: Wed, 4 Dec 2024 13:26:58 -0600 Subject: [PATCH] Support creation of Sphinx documentation --- README.md | 7 +++++++ docs/Makefile | 20 ++++++++++++++++++++ docs/conf.py | 31 +++++++++++++++++++++++++++++++ docs/development.md | 29 +++++++++++++++++++++++++++++ docs/index.rst | 14 ++++++++++++++ docs/make.bat | 35 +++++++++++++++++++++++++++++++++++ docs/readme.rst | 2 ++ 7 files changed, 138 insertions(+) create mode 100644 docs/Makefile create mode 100644 docs/conf.py create mode 100644 docs/development.md create mode 100644 docs/index.rst create mode 100644 docs/make.bat create mode 100644 docs/readme.rst diff --git a/README.md b/README.md index 8d0f530..88930a5 100644 --- a/README.md +++ b/README.md @@ -32,6 +32,13 @@ If you intend to develop the code for your proposes or contribute to the open so * Run tests `python -m pytest` +### Building the documentation +* Activate virtual env (see Install from source) +* Install sphinx and myst-parser + `pip install sphinx myst-parser` +* Run sphinx-build command + `sphinx-build ./docs ./dist/docs` + ### Commands: 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/conf.py b/docs/conf.py new file mode 100644 index 0000000..58ed402 --- /dev/null +++ b/docs/conf.py @@ -0,0 +1,31 @@ +# 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 = 'qct-parse' +copyright = '2024, AMIA Open-Source' +author = 'AMIA Open-Source' + +# -- General configuration --------------------------------------------------- +# https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration + +extensions = ['myst_parser'] + +templates_path = ['_templates'] +exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store'] + +source_suffix = { + '.rst': 'restructuredtext', + '.txt': 'markdown', + '.md': 'markdown', +} + +# -- 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'] diff --git a/docs/development.md b/docs/development.md new file mode 100644 index 0000000..227caeb --- /dev/null +++ b/docs/development.md @@ -0,0 +1,29 @@ +# Development Information + +## Configure Development Environment + +* Create a new Python Virtual Environment for qct_parse + * Unix based (Mac or Linux): + `python3 -m venv name_of_env` + * Windows: + `py -m venv name_of_env` + (where 'name_of_env' is replaced with the name of your virtual environment) +* Activate virtual env + * Unix based (Mac or Linux): + `source ./name_of_env/bin/activate` + * Windows: + `name_of_env\scripts\activate` +* Install Package as editable package + * Navigate to the repo root directory `path/to/qct-parse/` + * Run the command: + `python -m pip install -e .` + +## Run Tests + +If you intend to develop the code for your proposes or contribute to the open source project, a test directory is provided in the repo. +* Activate virtual env (see Configure Development Environment) +* Install pytest + `pip install pytest` +* Run tests + `python -m pytest` + diff --git a/docs/index.rst b/docs/index.rst new file mode 100644 index 0000000..7ebe75d --- /dev/null +++ b/docs/index.rst @@ -0,0 +1,14 @@ +.. qct-parse documentation master file, created by + sphinx-quickstart on Tue Dec 3 20:53:22 2024. + You can adapt this file completely to your liking, but it should at least + contain the root `toctree` directive. + +qct-parse documentation +======================= + +.. toctree:: + :maxdepth: 2 + :caption: Contents: + + readme + development diff --git a/docs/make.bat b/docs/make.bat new file mode 100644 index 0000000..954237b --- /dev/null +++ b/docs/make.bat @@ -0,0 +1,35 @@ +@ECHO OFF + +pushd %~dp0 + +REM Command file for Sphinx documentation + +if "%SPHINXBUILD%" == "" ( + set SPHINXBUILD=sphinx-build +) +set SOURCEDIR=. +set BUILDDIR=_build + +%SPHINXBUILD% >NUL 2>NUL +if errorlevel 9009 ( + echo. + echo.The 'sphinx-build' command was not found. Make sure you have Sphinx + echo.installed, then set the SPHINXBUILD environment variable to point + echo.to the full path of the 'sphinx-build' executable. Alternatively you + echo.may add the Sphinx directory to PATH. + echo. + echo.If you don't have Sphinx installed, grab it from + echo.https://www.sphinx-doc.org/ + exit /b 1 +) + +if "%1" == "" goto help + +%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O% +goto end + +:help +%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O% + +:end +popd diff --git a/docs/readme.rst b/docs/readme.rst new file mode 100644 index 0000000..339dc8f --- /dev/null +++ b/docs/readme.rst @@ -0,0 +1,2 @@ +.. include:: ../README.md + :parser: myst_parser.sphinx_