diff --git a/.github/workflows/build_docs.yml b/.github/workflows/build_docs.yml new file mode 100644 index 000000000..db6efd3c6 --- /dev/null +++ b/.github/workflows/build_docs.yml @@ -0,0 +1,44 @@ +name: Build Sphinx docs + +on: + pull_request: + branches: + - main + +permissions: + contents: read + pages: read + +jobs: + # Build job + build: + runs-on: ubuntu-latest + container: metaseqopt.azurecr.io/metaseq-opt-singularity:latest + + steps: + - name: Checkout + uses: actions/checkout@v3 + + - name: Set up Python 3.8 + uses: actions/setup-python@v2 + with: + python-version: 3.8 + + - name: Setup Pages + id: pages + uses: actions/configure-pages@v3 + + - name: Build Metaseq and Install dependencies + run: | + conda run -n ptca pip install --user -e ".[dev,docs]" + conda run -n ptca python setup.py install --user + + - name: Build Sphinx docs using Make + run: | + cd docs + make html + + - name: Upload Sphinx HTML as Action Artifact + uses: actions/upload-pages-artifact@v1 + with: + path: docs/build/html diff --git a/.github/workflows/deploy_docs.yml b/.github/workflows/deploy_docs.yml new file mode 100644 index 000000000..4252b8982 --- /dev/null +++ b/.github/workflows/deploy_docs.yml @@ -0,0 +1,64 @@ +name: Deploy Sphinx docs to Github Pages + +on: + # Runs on pushes targeting the default branch + push: + branches: + - main + +# Sets permissions of the GITHUB_TOKEN to allow deployment to GitHub Pages +permissions: + contents: read + pages: write + id-token: write + +# Allow one concurrent deployment +concurrency: + group: "pages" + cancel-in-progress: true + +jobs: + # Build job + build: + runs-on: ubuntu-latest + container: metaseqopt.azurecr.io/metaseq-opt-singularity:latest + + steps: + - name: Checkout + uses: actions/checkout@v3 + + - name: Set up Python 3.8 + uses: actions/setup-python@v2 + with: + python-version: 3.8 + + - name: Setup Pages + id: pages + uses: actions/configure-pages@v3 + + - name: Build Metaseq and Install dependencies + run: | + conda run -n ptca pip install --user -e ".[dev,docs]" + conda run -n ptca python setup.py install --user + + - name: Build Sphinx docs using Make + run: | + cd docs + make html + + - name: Upload Sphinx HTML as Action Artifact + uses: actions/upload-pages-artifact@v1 + with: + path: docs/build/html + + # Deployment job + deploy: + environment: + name: github-pages + url: ${{ steps.deployment.outputs.page_url }} + runs-on: ubuntu-latest + needs: build + steps: + - name: Deploy to GitHub Pages + id: deployment + uses: actions/deploy-pages@v1 diff --git a/docs/Makefile b/docs/Makefile new file mode 100644 index 000000000..1c3166c55 --- /dev/null +++ b/docs/Makefile @@ -0,0 +1,31 @@ +# Minimal makefile for Sphinx documentation +# + +# You can set these variables from the command line, and also +# from the environment for the first two. +# TODO: Investigate errors during first build +# SPHINXOPTS ?= -W --keep-going -n +SPHINXOPTS ?= +SPHINXBUILD ?= sphinx-build +SOURCEDIR = source +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) + +# serves html version of documentation +serve: + cd build/html && http-server -v + +# start a watch process that automatically rebuilds the HTML version of +# the doc every time a file is changed in the `source` folder +watch: + watchexec -w .. -e md,rst,py $(MAKE) html diff --git a/docs/source/conf.py b/docs/source/conf.py new file mode 100644 index 000000000..e80d07c7a --- /dev/null +++ b/docs/source/conf.py @@ -0,0 +1,109 @@ +# 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 +import datetime + +project = 'Metaseq' +copyright = f'{datetime.datetime.now().year} , Meta' +author = 'Meta Research' + +# -- Path setup -------------------------------------------------------------- + +# If extensions (or modules to document with autodoc) are in another directory, +# add these directories to sys.path here. If the directory is relative to the +# documentation root, use os.path.abspath to make it absolute, like shown here. +# +from glob import glob +import os +import shutil +import sys + +sys.path.insert(0, os.path.abspath('../..')) + +# -- General configuration --------------------------------------------------- + +# Add any Sphinx extension module names here, as strings. They can be +# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom +# ones. +extensions = [ + "myst_parser", + "sphinx.ext.autodoc", + "sphinx.ext.napoleon", + "sphinx.ext.intersphinx", + "sphinx.ext.viewcode", + 'sphinx_copybutton', + "sphinx_design", + "sphinxcontrib.mermaid", +] + +myst_enable_extensions = [ + "amsmath", + "colon_fence", + "deflist", + "dollarmath", + "fieldlist", + "html_admonition", + "html_image", + "linkify", + "replacements", + "smartquotes", + "strikethrough", + "substitution", + "tasklist", +] + +# Add any paths that contain templates here, relative to this directory. +templates_path = ['_templates'] + +# List of patterns, relative to source directory, that match files and +# directories to ignore when looking for source files. +# This pattern also affects html_static_path and html_extra_path. +exclude_patterns = ["_build", "Thumbs.db", ".DS_Store"] + +suppress_warnings = ["myst.strikethrough"] + +# -- Options for HTML output ------------------------------------------------- + +# The theme to use for HTML and HTML Help pages. See the documentation for +# a list of builtin themes. +# +html_theme = "furo" +html_title = "Metaseq Documentation" +html_theme_options = { + "source_repository": "https://github.com/facebookresearch/metaseq", + "source_branch": "main", + "source_directory": "docs/source", +} + +# Add any paths that contain custom static files (such as style sheets) here, +# relative to this directory. They are copied after the builtin static files, +# so a file named "default.css" will overwrite the builtin "default.css". +html_static_path = ['_static'] +html_css_files = ["custom.css"] + +# html_logo = "_static/images/logo.svg" +# html_favicon = '_static/images/logo.svg' + +autodoc_typehints = 'none' +autodoc_member_order = 'groupwise' +autodoc_default_options = { + 'members': True, + 'member-order': 'bysource', + 'special-members': '__init__', + 'exclude-members': '__weakref__' +} + +# allows us to automatically link to documentation from other libraries +intersphinx_mapping = { + "numpy": ("http://docs.scipy.org/doc/numpy/", None), + "python": ("https://docs.python.org/3.8", None), + "torch": ("https://pytorch.org/docs/master/", None), +} + +# -- LaTeX output ------------------------------------------------- + +latex_engine = "xelatex" diff --git a/docs/source/index.md b/docs/source/index.md new file mode 100644 index 000000000..a4612fec3 --- /dev/null +++ b/docs/source/index.md @@ -0,0 +1,17 @@ +--- +sd_hide_title: true +--- + +# Dummy Title + +```{toctree} +:hidden: +:caption: Modifying This Documentation +:glob: + +modifying_documentation/* +``` + +# Metaseq + +Link to MetaSeq repo diff --git a/docs/source/modifying_documentation/autodoc_syntax_example.md b/docs/source/modifying_documentation/autodoc_syntax_example.md new file mode 100644 index 000000000..742f338d7 --- /dev/null +++ b/docs/source/modifying_documentation/autodoc_syntax_example.md @@ -0,0 +1,21 @@ +# Embed Module or Function members + +% For explanation of the autodoc generator check out: https://www.sphinx-doc.org/en/master/usage/extensions/autodoc.html + +## Module Members + +```{eval-rst} +.. automodule:: metaseq.cli.train + :members: +``` + +## Method Members + +```{eval-rst} +.. automodule:: metaseq.cli.validate +.. automethod:: metaseq.cli.validate.main(cfg, override_args) + +.. .. autoclass:: Run +.. :inherited-members: +.. :members: +``` diff --git a/docs/source/modifying_documentation/interdoc_links_example.md b/docs/source/modifying_documentation/interdoc_links_example.md new file mode 100644 index 000000000..e45a68ec4 --- /dev/null +++ b/docs/source/modifying_documentation/interdoc_links_example.md @@ -0,0 +1,9 @@ +# Linking to other Sphinx documentation + +You can link between Sphinx documentation using a `{ref}` instead of a typical URL. + +## Examples + +- {ref}`Custom Link Text (Torch Utilities) ` +- {ref}`torch:generated/torch.cuda.streamcontext:streamcontext` +- {ref}`torch:community/contribution_guide:getting started` diff --git a/docs/source/modifying_documentation/mermaid_example.md b/docs/source/modifying_documentation/mermaid_example.md new file mode 100644 index 000000000..264481692 --- /dev/null +++ b/docs/source/modifying_documentation/mermaid_example.md @@ -0,0 +1,31 @@ +# Example using Mermaid + +[Mermaid](https://mermaid.js.org/intro/) is a JavaScript based diagramming and charting tool that uses Markdown-inspired text definitions and a renderer to create and modify complex diagrams. + +(section-two)= +## Here's another section + +% This comment won't make it into the outputs! + +And here's {ref}`a reference to this section `. +I can also reference the section {ref}`section-two` without specifying my title. + +:::{note} +And here's a note with a colon fence! +::: + +And finally, here's a cool mermaid diagram! + +```{mermaid} +sequenceDiagram + participant Alice + participant Bob + Alice->John: Hello John, how are you? + loop Healthcheck + John->John: Fight against hypochondria + end + Note right of John: Rational thoughts
prevail... + John-->Alice: Great! + John->Bob: How about you? + Bob-->John: Jolly good! +``` diff --git a/docs/source/modifying_documentation/overview.md b/docs/source/modifying_documentation/overview.md new file mode 100644 index 000000000..5ef522e6b --- /dev/null +++ b/docs/source/modifying_documentation/overview.md @@ -0,0 +1,40 @@ +# Overview + +## Background + +- HTML Documentation is generated using Sphinx +- Theme: [Furo](https://pradyunsg.me/furo/reference/) + - Here you find information about the reST or Markdown syntax processed by the theme +- Extensions: + - Support for Markdown (.md) and ReStructured Text (.rst) using [Markedly Structured Text (MyST)](https://myst-parser.readthedocs.io/en/latest/intro.html) + - Support for Mermaid Diagrams + +## Installing Sphinx Dependencies + +If using the .devcontainer, this should already be done. However, you can do it manually by installing the `docs` extra: + +```bash +# From the root folder of the repo +pip install -e ".[docs]" +``` + +## Building the Documentation + +```bash +# Watch /docs/source folder and rebuild the documentation on file change +make watch +``` + +This will output to the `/docs/build` folder + +## Viewing the Documentation + +```bash +# Start server to view the documentation +make serve +``` + +### Open the URL in command output + +http://127.0.0.1:7878/index.html + diff --git a/setup.py b/setup.py index 197bd41df..1b4d78ba2 100644 --- a/setup.py +++ b/setup.py @@ -324,6 +324,16 @@ def do_setup(): "wandb", "webdataset==0.1.103", ], + "docs": [ + "Sphinx", + "myst-parser==0.18.1", + "sphinxcontrib-mermaid==0.8.1", + "linkify-it-py==2.0.0", + "sphinx-copybutton==0.5.1", + "sphinx_design==0.3.0", + "furo==2022.12.7", + "tabulate==0.9.0", + ], }, ext_modules=extension_modules, test_suite="tests",