diff --git a/.github/workflows/tests.yml b/.github/workflows/tests.yml index 367983989..7a648c5d4 100644 --- a/.github/workflows/tests.yml +++ b/.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 diff --git a/.readthedocs.yaml b/.readthedocs.yaml new file mode 100644 index 000000000..49eee0353 --- /dev/null +++ b/.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 diff --git a/README.md b/README.md index d75df5b2b..0bc6fe7c5 100644 --- a/README.md +++ b/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. - diff --git a/docker/faabric-base.dockerfile b/docker/faabric-base.dockerfile index 016c368de..10802f718 100644 --- a/docker/faabric-base.dockerfile +++ b/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 diff --git a/docs/.gitignore b/docs/.gitignore new file mode 100644 index 000000000..b9244c26a --- /dev/null +++ b/docs/.gitignore @@ -0,0 +1,3 @@ +doxygen/ +apidoc/ +sphinx/ diff --git a/docs/Doxyfile b/docs/Doxyfile new file mode 100644 index 000000000..e34fbae45 --- /dev/null +++ b/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 diff --git a/docs/conf.py b/docs/conf.py new file mode 100644 index 000000000..dddf2a98d --- /dev/null +++ b/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") diff --git a/docs/index.rst b/docs/index.rst new file mode 100644 index 000000000..91f475c55 --- /dev/null +++ b/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 diff --git a/docs/development.md b/docs/source/development.md similarity index 100% rename from docs/development.md rename to docs/source/development.md diff --git a/docs/mpi_native.md b/docs/source/mpi_native.md similarity index 100% rename from docs/mpi_native.md rename to docs/source/mpi_native.md diff --git a/include/faabric/endpoint/Endpoint.h b/include/faabric/endpoint/Endpoint.h index d335b66ea..c77b4ad8a 100644 --- a/include/faabric/endpoint/Endpoint.h +++ b/include/faabric/endpoint/Endpoint.h @@ -6,6 +6,10 @@ #include namespace faabric::endpoint { + +/** + * Superclass for HTTP endpoints. + */ class Endpoint { public: diff --git a/requirements.txt b/requirements.txt index e6c0d85d2..9f520d22a 100644 --- a/requirements.txt +++ b/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 diff --git a/tasks/__init__.py b/tasks/__init__.py index 5bc3f368f..77664b2c6 100644 --- a/tasks/__init__.py +++ b/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, diff --git a/tasks/docs.py b/tasks/docs.py new file mode 100644 index 000000000..5754d6488 --- /dev/null +++ b/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, + ) diff --git a/tasks/util/env.py b/tasks/util/env.py index 44a080591..34f96c33d 100644 --- a/tasks/util/env.py +++ b/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")