Generate documentation (faasm#223)

* Skeleton for docs

* Remove autogen makefile

* Tidy-up

* Add directory to cache actioN

* RTD config file

* Hack to install deps

* Added breathe-apidoc

* Simplify sphinx build

* Revert unnecessary changes to GHA

* Populate classes with members, rtd theme

* Remove comment

* Update README

* Formatting

* Check out code in docs build

* Remove conan-cache dep from docs build

.github/workflows/tests.yml

@@ -27,6 +27,26 @@ jobs:
       - name: "Build dependencies to be shared by all runs"
         run: inv dev.cmake -b Debug
 
+  docs:
+    if: github.event.pull_request.draft == false
+    runs-on: ubuntu-latest
+    container:
+      image: faasm/faabric:0.2.4
+    defaults:
+      run:
+        working-directory: /code/faabric
+    steps:
+      - name: "Fetch ref"
+        run: git fetch origin ${GITHUB_REF}:ci-branch
+      - name: "Check out branch"
+        run: git checkout --force ci-branch
+      - name: "TEMP - install doxygen"
+        run: apt install -y doxygen
+      - name: "TEMP - install python deps"
+        run: pip install -r requirements.txt
+      - name: "Build docs"
+        run: inv docs
+
   formatting:
     if: github.event.pull_request.draft == false
     runs-on: ubuntu-latest

.readthedocs.yaml

@@ -0,0 +1,13 @@
+version: 2
+
+build:
+  os: "ubuntu-20.04"
+  tools:
+    python: "3.9"
+
+sphinx:
+  configuration: docs/conf.py
+
+python:
+  install:
+    - requirements: requirements.txt

README.md

@@ -6,12 +6,10 @@ distributed serverless runtimes.
 It began life as part of [Faasm](https://github.com/faasm/faasm), but is now a
 stand-alone library that can be used as a base for other distributed runtimes.
 
+See the [documentation](https://faabric.readthedocs.io/en/latest/) for more
+details.
+
 ## Usage
 
 You can see a simple example in the [examples](examples) directory.
 
-## Development
-
-See the [development docs](docs/development.md) for more information on
-developing Faabric.
-

docker/faabric-base.dockerfile

@@ -22,6 +22,7 @@ RUN apt install -y \
     clang-tidy-13 \
     clang-tools-13 \
     cmake \
+    doxygen \
     g++-11 \
     git \
     kitware-archive-keyring \
@@ -50,6 +51,9 @@ RUN apt install -y \
 
 RUN curl -s -L -o /tmp/conan-latest.deb https://github.com/conan-io/conan/releases/download/1.43.0/conan-ubuntu-64.deb && sudo dpkg -i /tmp/conan-latest.deb && rm -f /tmp/conan-latest.deb
 
+# Update pip
+RUN pip install -U pip
+
 # Tidy up
 RUN apt-get clean autoclean
 RUN apt-get autoremove

docs/.gitignore

@@ -0,0 +1,3 @@
+doxygen/
+apidoc/
+sphinx/

docs/Doxyfile

@@ -0,0 +1,16 @@
+DOXYFILE_ENCODING = UTF-8
+PROJECT_NAME      = "Faabric"
+OUTPUT_DIRECTORY  = doxygen
+OUTPUT_LANGUAGE   = English
+
+FULL_PATH_NAMES   = NO
+MARKDOWN_SUPPORT  = YES
+RECURSIVE         = YES
+QUIET             = YES
+
+GENERATE_LATEX    = NO
+GENERATE_XML      = YES
+GENERATE_HTML     = NO
+
+INPUT             = ../include ../src
+FILE_PATTERNS     = *.h *.cpp

docs/conf.py

@@ -0,0 +1,40 @@
+from os.path import dirname, realpath, join
+from subprocess import run
+from os import makedirs
+
+# ----------------------------------------
+# This is the Sphinx configuration file, which wraps
+# the calls to Doxygen and Breathe.
+# ----------------------------------------
+
+DOCS_ROOT = dirname(realpath(__file__))
+DOXYGEN_OUT = join(DOCS_ROOT, "doxygen", "xml")
+APIDOC_OUT_DIR = join(DOCS_ROOT, "apidoc")
+
+makedirs(APIDOC_OUT_DIR, exist_ok=True)
+
+run("doxygen", cwd=DOCS_ROOT, check=True, shell=True)
+
+run(
+    "breathe-apidoc {} -o {} -f -m".format(DOXYGEN_OUT, APIDOC_OUT_DIR),
+    cwd=DOCS_ROOT,
+    check=True,
+    shell=True,
+)
+
+project = "Faabric"
+copyright = "2022, Simon Shillaker"
+author = "Simon Shillaker"
+
+extensions = ["breathe", "myst_parser", "sphinx_rtd_theme"]
+
+templates_path = ["source/templates"]
+html_static_path = ["source/static"]
+
+exclude_patterns = ["_build", "Thumbs.db", ".DS_Store"]
+
+html_theme = "sphinx_rtd_theme"
+
+breathe_projects = {"Faabric": DOXYGEN_OUT}
+breathe_default_project = "Faabric"
+breathe_default_members = ("members", "undoc-members")

docs/index.rst

@@ -0,0 +1,19 @@
+Faabric Documentation
+===================================
+
+These docs include some pages on specific topics, as well as the autogenerated
+docs from the code.
+
+.. toctree::
+   :maxdepth: 2
+   :caption: Topics
+
+   source/development
+   source/mpi_native
+
+.. toctree::
+   :maxdepth: 1
+   :caption: Code
+
+   apidoc/namespacelist
+   apidoc/classlist

include/faabric/endpoint/Endpoint.h

@@ -6,6 +6,10 @@
 #include <pistache/http.h>
 
 namespace faabric::endpoint {
+
+/**
+ * Superclass for HTTP endpoints.
+ */
 class Endpoint
 {
   public:

requirements.txt

@@ -1,7 +1,9 @@
-ansible
-black
-docker
-flake8
-invoke
-numpy
-redis
+black==21.12b0
+breathe==4.32.0
+docker==5.0.3
+flake8==4.0.1
+invoke==1.6.0
+myst-parser==0.16.1
+numpy==1.21.5
+redis==4.1.0
+sphinx-rtd-theme==1.0.0

tasks/__init__.py

@@ -3,6 +3,7 @@
 from . import call
 from . import container
 from . import dev
+from . import docs
 from . import examples
 from . import git
 from . import mpi_native
@@ -11,6 +12,7 @@
     call,
     container,
     dev,
+    docs,
     examples,
     git,
     mpi_native,

tasks/docs.py

@@ -0,0 +1,22 @@
+from os import makedirs
+from os.path import join
+from subprocess import run
+
+from tasks.util.env import PROJ_ROOT
+
+from invoke import task
+
+DOCS_DIR = join(PROJ_ROOT, "docs")
+SPHINX_OUT_DIR = join(DOCS_DIR, "sphinx")
+
+
+@task(default=True)
+def generate(ctx):
+    makedirs(SPHINX_OUT_DIR, exist_ok=True)
+
+    run(
+        "sphinx-build -b html {} {}".format(DOCS_DIR, SPHINX_OUT_DIR),
+        cwd=DOCS_DIR,
+        check=True,
+        shell=True,
+    )

tasks/util/env.py

@@ -3,7 +3,6 @@
 
 HOME_DIR = expanduser("~")
 PROJ_ROOT = dirname(dirname(dirname(realpath(__file__))))
-ANSIBLE_ROOT = join(PROJ_ROOT, "ansible")
 
 _FAABRIC_BUILD_DIR = environ.get("FAABRIC_BUILD_DIR", "/build/faabric")