doc: basic structure and RTD support

sehoffmann · Oct 25, 2024 · f5776d3 · f5776d3
1 parent c08b12a
commit f5776d3
Show file tree

Hide file tree

Showing 10 changed files with 80 additions and 19 deletions.
diff --git a/.readthedocs.yaml b/.readthedocs.yaml
@@ -0,0 +1,32 @@
+# .readthedocs.yaml
+# Read the Docs configuration file
+# See https://docs.readthedocs.io/en/stable/config-file/v2.html for details
+
+# Required
+version: 2
+
+# Set the OS, Python version and other tools you might need
+build:
+  os: ubuntu-22.04
+  tools:
+    python: "3.12"
+    # You can also specify other tool versions:
+    # nodejs: "19"
+    # rust: "1.64"
+    # golang: "1.19"
+
+# Build documentation in the "docs/" directory with Sphinx
+sphinx:
+  configuration: doc/conf.py
+
+# Optionally build your docs in additional formats such as PDF and ePub
+# formats:
+#    - pdf
+#    - epub
+
+# Optional but recommended, declare the Python requirements required
+# to build your documentation
+# See https://docs.readthedocs.io/en/stable/guides/reproducible-builds.html
+python:
+    install:
+    - requirements: ci_requirements.txt
diff --git a/dmlcloud/__init__.py b/dmlcloud/__init__.py
@@ -1,3 +1,6 @@
+"""
+"""
+
 from dmlcloud.stage import Stage, TrainValStage
 
 __version__ = "0.3.3"

diff --git a/dmlcloud/stage.py b/dmlcloud/stage.py
@@ -15,6 +15,7 @@
     'TrainValStage',
 ]
 
+
 class Stage:
     """
     Hook Points:

diff --git a/doc/conf.py b/doc/conf.py
@@ -6,8 +6,6 @@
 # -- Project information -----------------------------------------------------
 # https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information
 
-import dmlcloud
-
 project = 'dmlcloud'
 copyright = '2024, Sebastian Hoffmann'
 author = 'Sebastian Hoffmann'
@@ -27,7 +25,6 @@
 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
 

diff --git a/doc/generated/dmlcloud.rst b/doc/generated/dmlcloud.rst
@@ -0,0 +1,4 @@
+dmlcloud
+========
+
+.. automodule:: dmlcloud
diff --git a/doc/getting_started/index.rst b/doc/getting_started/index.rst
@@ -0,0 +1,25 @@
+Getting Started
+===============
+
+Installation
+------------
+Dmlcloud can be installed directly from PyPI::
+
+    pip install dmlcloud
+
+The latest development version can be installed from GitHub::
+
+    pip install git+https://github.com/sehoffmann/dmlcloud.git
+
+
+Optional Dependencies
+---------------------
+* wandb
+* xarray
+* mpi4py
+
+.. toctree::
+    :maxdepth: 2
+    :hidden:
+
+    mnist
diff --git a/doc/getting_started/mnist.rst b/doc/getting_started/mnist.rst
@@ -0,0 +1,4 @@
+Training on MNIST
+=================
+
+A simple example on MNIST.
diff --git a/doc/index.rst b/doc/index.rst
@@ -1,19 +1,10 @@
-.. 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
+dmlcloud documentation
 ======================
 
-Add your content using ``reStructuredText`` syntax. See the
-`reStructuredText <https://www.sphinx-doc.org/en/master/usage/restructuredtext/index.html>`_
-documentation for details.
-
 .. toctree::
-   :caption: Contents:
-
-   reference
-
+   :maxdepth: 3
 
+   Getting Started <getting_started/index>
+   User Guide <user_guide/index>
 
+   API Reference <reference>
diff --git a/doc/reference.rst b/doc/reference.rst
@@ -1,7 +1,9 @@
-Reference
+API Reference
 =========
 
+This is an automatically generated API reference for the dmlcloud package.
+
 .. autosummary::
    :toctree: generated
 
-   dmlcloud
+   dmlcloud
diff --git a/doc/user_guide/index.rst b/doc/user_guide/index.rst
@@ -0,0 +1,2 @@
+User Guide
+==========
-Original file line number
+Diff line change
@@ Expand Up / @@ -15,6 +15,7 @@ @@
         'TrainValStage',
     ]
     class Stage:
         """
         Hook Points:
@@ Expand Down @@