From 3458cabeb2b73a97998f9e51b1e3a772d0d86389 Mon Sep 17 00:00:00 2001 From: Sebastian Hoffmann Date: Wed, 23 Oct 2024 18:28:30 +0200 Subject: [PATCH] doc: basic sphinx setup --- .gitignore | 1 + ci_requirements.txt | 1 + dmlcloud/__init__.py | 7 ++++++- dmlcloud/stage.py | 4 ++++ doc/Makefile | 20 ++++++++++++++++++++ doc/conf.py | 32 ++++++++++++++++++++++++++++++++ doc/index.rst | 19 +++++++++++++++++++ doc/make.bat | 35 +++++++++++++++++++++++++++++++++++ doc/reference.rst | 7 +++++++ 9 files changed, 125 insertions(+), 1 deletion(-) create mode 100644 doc/Makefile create mode 100644 doc/conf.py create mode 100644 doc/index.rst create mode 100644 doc/make.bat create mode 100644 doc/reference.rst diff --git a/.gitignore b/.gitignore index 9267900..332d66b 100644 --- a/.gitignore +++ b/.gitignore @@ -1,6 +1,7 @@ /data /slurm-*.out /wandb +/doc/_build ############################ Auto Generated ############################ diff --git a/ci_requirements.txt b/ci_requirements.txt index 9c2ec3b..a3c7096 100644 --- a/ci_requirements.txt +++ b/ci_requirements.txt @@ -4,3 +4,4 @@ wheel build pre-commit pytest +sphinx diff --git a/dmlcloud/__init__.py b/dmlcloud/__init__.py index c10549f..69510e9 100644 --- a/dmlcloud/__init__.py +++ b/dmlcloud/__init__.py @@ -1,3 +1,8 @@ +from dmlcloud.stage import Stage, TrainValStage + __version__ = "0.3.3" -__all__ = [] +__all__ = [ + 'Stage', + 'TrainValStage', +] diff --git a/dmlcloud/stage.py b/dmlcloud/stage.py index db5eab1..6cf4e33 100644 --- a/dmlcloud/stage.py +++ b/dmlcloud/stage.py @@ -10,6 +10,10 @@ from .util.distributed import is_root from .util.logging import DevNullIO, flush_log_handlers +__all__ = [ + 'Stage', + 'TrainValStage', +] class Stage: """ diff --git a/doc/Makefile b/doc/Makefile new file mode 100644 index 0000000..d4bb2cb --- /dev/null +++ b/doc/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/doc/conf.py b/doc/conf.py new file mode 100644 index 0000000..3e44836 --- /dev/null +++ b/doc/conf.py @@ -0,0 +1,32 @@ +# 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 = 'dmlcloud' +copyright = '2024, Sebastian Hoffmann' +author = 'Sebastian Hoffmann' +release = 'v0.3.3' + +# -- General configuration --------------------------------------------------- +# https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration + +extensions = [ + 'sphinx.ext.duration', + 'sphinx.ext.autodoc', + 'sphinx.ext.autosummary', +] + +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 = 'classic' +html_static_path = ['_static'] diff --git a/doc/index.rst b/doc/index.rst new file mode 100644 index 0000000..f128f9b --- /dev/null +++ b/doc/index.rst @@ -0,0 +1,19 @@ +.. dmlcloud documentation master file, created by + sphinx-quickstart on Wed Oct 23 17:33:47 2024. + You can adapt this file completely to your liking, but it should at least + contain the root `toctree` directive. + +dmlcloud +====================== + +Add your content using ``reStructuredText`` syntax. See the +`reStructuredText `_ +documentation for details. + +.. toctree:: + :caption: Contents: + + reference + + + diff --git a/doc/make.bat b/doc/make.bat new file mode 100644 index 0000000..32bb245 --- /dev/null +++ b/doc/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/doc/reference.rst b/doc/reference.rst new file mode 100644 index 0000000..2ce41ab --- /dev/null +++ b/doc/reference.rst @@ -0,0 +1,7 @@ +Reference +========= + +.. autosummary:: + :toctree: generated + + dmlcloud \ No newline at end of file