📝 Setup Read the Docs

probabilists · Jan 21, 2023 · 882b821 · 882b821
1 parent 75d41f4
commit 882b821
Show file tree

Hide file tree

Showing 16 changed files with 55 additions and 49 deletions.
diff --git a/.gitignore b/.gitignore
@@ -6,7 +6,8 @@
 .DS_Store
 
 # Docs
-docs/
+docs/api/
+docs/html/
 
 
 ##########

diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -6,7 +6,7 @@ This document is a set of guidelines for contributing to the `zuko` package, whi
 
 ## I just have a question
 
-Please **don't file an issue** to ask a question. We use [GitHub discussions](https://github.com/francois-rozet/zuko/discussions) as community forum for people to ask questions, share ideas or seek help. Before submitting your question, check whether it is addressed by the [documentation](https://francois-rozet.github.io/zuko) or has already been asked in the discussions. If it has but the answer does not satisfy you, add a comment to the existing discussion instead of opening a new one.
+Please **don't file an issue** to ask a question. We use [GitHub discussions](https://github.com/francois-rozet/zuko/discussions) as community forum for people to ask questions, share ideas or seek help. Before submitting your question, check whether it is addressed by the [documentation](https://zuko.readthedocs.io) or has already been asked in the discussions. If it has but the answer does not satisfy you, add a comment to the existing discussion instead of opening a new one.
 
 ## Submit an issue
 
@@ -45,11 +45,12 @@ When you submit a pull request, tests are automatically (upon approval) executed
 
 ### Documentation
 
-The package's [documentation](https://francois-rozet.github.io/zuko) is automatically built by [Sphinx](https://www.sphinx-doc.org) using type hints and docstrings. All classes and functions accessible to the user should be documented with [Google style](https://google.github.io/styleguide/pyguide.html#38-comments-and-docstrings) docstrings. After installing the documentation dependencies (`sphinx` and `furo`), you can build it with
+The package's [documentation](https://zuko.readthedocs.io) is automatically built by [Sphinx](https://www.sphinx-doc.org) using type hints and docstrings. All classes and functions accessible to the user should be documented with [Google style](https://google.github.io/styleguide/pyguide.html#38-comments-and-docstrings) docstrings. You can build it locally with
 
 ```
-cd sphinx
-bash build.sh
+cd docs
+pip install -r requirements.txt
+sphinx-build . html
 ```
 
 ### Commits

diff --git a/README.md b/README.md
@@ -1,4 +1,4 @@
-![Zuko's banner](https://raw.githubusercontent.com/francois-rozet/zuko/master/sphinx/images/banner.svg)
+![Zuko's banner](https://raw.githubusercontent.com/francois-rozet/zuko/master/docs/images/banner.svg)
 
 # Zuko - Normalizing flows in PyTorch
 
@@ -43,8 +43,8 @@ log_p = flow(y).log_prob(x)
 x = flow(y).sample((64,))
 ```
 
-For more information about the available features check out the documentation at [francois-rozet.github.io/zuko](https://francois-rozet.github.io/zuko).
+For more information about the available features check out the documentation at [zuko.readthedocs.io](https://zuko.readthedocs.io).
 
 ## Contributing
 
-If you have a question, an issue or would like to contribute, please read our [contributing guidelines](CONTRIBUTING.md).
+If you have a question, an issue or would like to contribute, please read our [contributing guidelines](https://github.com/francois-rozet/zuko/blob/master/CONTRIBUTING.md).
diff --git a/sphinx/api.rst → docs/api.rst b/sphinx/api.rst → docs/api.rst
diff --git a/sphinx/conf.py → docs/conf.py b/sphinx/conf.py → docs/conf.py
@@ -1,14 +1,20 @@
 # Configuration file for the Sphinx documentation builder
 
+import glob
 import inspect
 import importlib
+import re
+import subprocess
+import zuko
 
 ## Project
 
 package = 'zuko'
 project = 'Zuko'
-copyright = '2022, François Rozet'
+version = zuko.__version__
+copyright = '2022-2023, François Rozet'
 repository = 'https://github.com/francois-rozet/zuko'
+commit = subprocess.check_output(['git', 'rev-parse', 'HEAD'], text=True).strip()
 
 ## Extensions
 
@@ -33,7 +39,6 @@
 autosummary_ignore_module_all = False
 
 intersphinx_mapping = {
-    'matplotlib': ('https://matplotlib.org/stable', None),
     'numpy': ('https://numpy.org/doc/stable', None),
     'python': ('https://docs.python.org/3', None),
     'torch': ('https://pytorch.org/docs/stable', None),
@@ -60,7 +65,7 @@ def linkcode_resolve(domain: str, info: dict) -> str:
     except Exception as e:
         return None
     else:
-        return f'{repository}/tree/docs/{file}#L{start}-L{end}'
+        return f'{repository}/blob/{commit}/{file}#L{start}-L{end}'
 
 
 napoleon_custom_sections = [
@@ -105,7 +110,7 @@ def linkcode_resolve(domain: str, info: dict) -> str:
     },
     'sidebar_hide_name': True,
 }
-html_title = project
+html_title = f'{project} {version}'
 pygments_style = 'sphinx'
 pygments_dark_style = 'monokai'
 rst_prolog = """
@@ -114,3 +119,23 @@ def linkcode_resolve(domain: str, info: dict) -> str:
     :language: python
 """
 templates_path = ['templates']
+
+## Edit HTML
+
+def edit_html(app, exception):
+    if exception:
+        raise exception
+
+    for file in glob.glob(f'{app.outdir}/**/*.html', recursive=True):
+        with open(file, 'r') as f:
+            text = f.read()
+
+        text = text.replace('<a class="muted-link" href="https://pradyunsg.me">@pradyunsg</a>\'s', '')
+        text = text.replace('<span class="pre">[source]</span>', '<i class="fa-solid fa-code"></i>')
+        text = re.sub(r'(<a class="reference external".*</a>)(<a class="headerlink".*</a>)', r'\2\1', text)
+
+        with open(file, 'w') as f:
+            f.write(text)
+
+def setup(app):
+    app.connect('build-finished', edit_html)
diff --git a/sphinx/docutils.conf → docs/docutils.conf b/sphinx/docutils.conf → docs/docutils.conf
diff --git a/sphinx/images/banner.svg → docs/images/banner.svg b/sphinx/images/banner.svg → docs/images/banner.svg
diff --git a/sphinx/images/banner_dark.svg → docs/images/banner_dark.svg b/sphinx/images/banner_dark.svg → docs/images/banner_dark.svg
diff --git a/sphinx/index.rst → docs/index.rst b/sphinx/index.rst → docs/index.rst
diff --git a/sphinx/requirements.txt → docs/requirements.txt b/sphinx/requirements.txt → docs/requirements.txt
diff --git a/sphinx/static/custom.css → docs/static/custom.css b/sphinx/static/custom.css → docs/static/custom.css
@@ -69,7 +69,7 @@ mjx-container[display="true"] {
 
 .sidebar-drawer {
     left: -18em;
-    min-width: 18em;\
+    min-width: 18em;
 }
 
 div.sidebar-container {

diff --git a/sphinx/static/logo.svg → docs/static/logo.svg b/sphinx/static/logo.svg → docs/static/logo.svg
diff --git a/sphinx/templates/autosummary/module.rst → docs/templates/autosummary/module.rst b/sphinx/templates/autosummary/module.rst → docs/templates/autosummary/module.rst
diff --git a/readthedocs.yml b/readthedocs.yml
@@ -0,0 +1,14 @@
+version: 2
+
+build:
+  os: ubuntu-22.04
+  tools:
+    python: "3.9"
+  jobs:
+    post_install:
+      - pip install -U setuptools
+      - pip install -e . --extra-index-url https://download.pytorch.org/whl/cpu
+      - pip install -r docs/requirements.txt
+
+sphinx:
+  configuration: docs/conf.py
diff --git a/setup.cfg b/setup.cfg
@@ -16,7 +16,7 @@ author_email = [email protected]
 license = MIT License
 url = https://github.com/francois-rozet/zuko
 project_urls =
-    Documentation = https://francois-rozet.github.io/zuko
+    Documentation = https://zuko.readthedocs.io
     Source = https://github.com/francois-rozet/zuko
     Tracker = https://github.com/francois-rozet/zuko/issues
 classifiers =

diff --git a/sphinx/build.sh b/sphinx/build.sh