Update and simplify documentation build

NaturalHPC · Mar 31, 2024 · 1b27a09 · 1b27a09
1 parent 834f2a1
commit 1b27a09
Show file tree

Hide file tree

Showing 11 changed files with 81 additions and 229 deletions.
diff --git a/.readthedocs.yaml b/.readthedocs.yaml
@@ -0,0 +1,17 @@
+version: 2
+
+build:
+  os: ubuntu-22.04
+  tools:
+    python: "3.12"
+
+python:
+  install:
+    - requirements: docs/requirements.txt
+    # install the package so that we have the dependencies and can import the files
+    - method: pip
+      path: .
+
+sphinx:
+  configuration: docs/source/conf.py
+  builder: html
diff --git a/docs/Makefile b/docs/Makefile
@@ -5,8 +5,8 @@
 SPHINXOPTS    =
 SPHINXBUILD   = sphinx-build
 SPHINXPROJ    = cerulean
-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/.gitignore b/docs/_static/.gitignore
diff --git a/docs/_templates/.gitignore b/docs/_templates/.gitignore
diff --git a/docs/conf.py b/docs/conf.py
diff --git a/docs/requirements.txt b/docs/requirements.txt
@@ -0,0 +1,5 @@
+docutils
+sphinx
+sphinx-rtd-theme
+recommonmark
+
diff --git a/docs/source/api.rst b/docs/source/api.rst
@@ -0,0 +1,6 @@
+API Reference
+=============
+
+
+.. automodule:: cerulean
+   :members:
diff --git a/docs/source/conf.py b/docs/source/conf.py
@@ -0,0 +1,38 @@
+# 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
+
+from os import path
+import sys
+
+# -- Project information -----------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information
+
+project = 'Cerulean'
+copyright = '2018-2019, 2024, The Netherlands eScience Center and VU University Amsterdam'
+author = 'Lourens Veen'
+
+release = '0.3.8.dev0'
+
+# -- General configuration ---------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration
+
+# apidoc needs to be able to import cerulean
+here = path.dirname(__file__)
+sys.path.insert(0, path.abspath(path.join(here, '..', '..')))
+
+extensions = ['sphinx.ext.autodoc', 'sphinx.ext.napoleon']
+
+templates_path = ['_templates']
+exclude_patterns = []
+
+root_doc = 'index'
+
+
+# -- Options for HTML output -------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output
+
+html_theme = 'sphinx_rtd_theme'
+html_static_path = ['_static']
+
diff --git a/docs/index.rst → docs/source/index.rst b/docs/index.rst → docs/source/index.rst
@@ -3,16 +3,17 @@
    You can adapt this file completely to your liking, but it should at least
    contain the root `toctree` directive.
 
+====================================
 Welcome to Cerulean's documentation!
-==========================================================
+====================================
 
 Cerulean is a Python 3 library for connecting to HPC compute resources, such as
 compute clusters and supercomputers. It lets you copy files between local and
 SFTP filesystems using a ``pathlib``-like API, it lets you start processes
 locally and remotely via SSH, and it lets you submit jobs to schedulers such as
 Slurm and Torque/PBS.
 
-Cerulean supports Python 3.4 and later.
+Cerulean supports Python 3.7 and later.
 
 .. toctree::
    :maxdepth: 2
@@ -21,13 +22,10 @@ Cerulean supports Python 3.4 and later.
    tutorial
 
 
-API Reference
-=============
-
 .. toctree::
-  :maxdepth: 1
+   :maxdepth: 1
 
-   API reference <apidocs/cerulean.rst>
+   api
 
 
 Indices and tables

diff --git a/docs/tutorial.rst → docs/source/tutorial.rst b/docs/tutorial.rst → docs/source/tutorial.rst
@@ -1,4 +1,3 @@
-========
 Tutorial
 ========
 
@@ -18,7 +17,7 @@ dependencies.
 
 
 Accessing files
-===============
+---------------
 
 The file access functions of Cerulean use a ``pathlib``-like API, but unlike in
 ``pathlib``, Cerulean supports remote file systems. That means that there is no
@@ -66,7 +65,7 @@ You can use the ``/`` operator to build paths from components as with
 documentation for :class:`cerulean.Path` for details.
 
 Remote filesystems
-------------------
+``````````````````
 
 Cerulean supports remote file systems through the SFTP protocol. (It uses the
 Paramiko library internally for this.) Accessing a remote file system through
@@ -105,7 +104,7 @@ from there it works just like a local file system. Just like
 another ``with``-statement.
 
 Copying files
--------------
+`````````````
 
 When running jobs on HPC machines, you often start with copying the input files
 from the local system to the HPC machine, and finish with copying the results
@@ -132,7 +131,7 @@ you would expect:
           cerulean.copy(job_dir / 'output.txt', output_file)
 
 Running commands
-================
+----------------
 
 If you have read the above, then the secret is already out: running commands
 using Cerulean is done using a :class:`Terminal`. For example, you can run a
@@ -173,7 +172,7 @@ except you use an :class:`SshTerminal`, as above:
 
 
 Submitting jobs
-===============
+---------------
 
 On High Performance Computing machines, you don't run commands directly.
 Instead, you submit batch jobs to a scheduler, which will place them in a queue,
@@ -215,7 +214,7 @@ the scheduler is local, and you want to use a :class:`LocalTerminal` with your
 
 
 More information
-================
+----------------
 
 To find all the details of what Cerulean can do and how to do it, please refer
-to the :doc:`API documentation<apidocs/cerulean>`.
+to the :doc:`API documentation<api>`.
diff --git a/pyproject.toml b/pyproject.toml
@@ -60,7 +60,7 @@ deps =
     sphinx
     sphinx-rtd-theme
     recommonmark
-commands = sphinx-build docs/ docs/_build/html -bhtml
+commands = sphinx-build -M html docs/source docs/build
 
 """