Merge pull request #2042 from mikedh/docs/examples

Docs: Render Examples

Author: mikedh

Dockerfile

@@ -105,7 +105,7 @@ RUN make
 
 ### Copy just the docs so we can output them
 FROM scratch as docs
-COPY --from=build_docs /home/user/docs/_build/html/ ./
+COPY --from=build_docs /home/user/docs/built/html/ ./
 
 ### Make sure the output stage is the last stage so a simple
 # "docker build ." still outputs an expected image

docs/Makefile

@@ -6,45 +6,45 @@ SPHINXGEN     ?= sphinx-apidoc
 NBCONVERT     ?= jupyter
 PYTHON        ?= python
 PIP           ?= pip
-SOURCEDIR     = .
-BUILDDIR      = _build
+BUILDDIR      = built
 TEMPLATESDIR  = templates
-STATICDIR     = _static
+# where to put generated RST files
+GENDIR        = generate
+CONTENT       = content
+STATICDIR     = static
+
 
 example_notebooks := $(wildcard ../examples/*.ipynb)
 example_notebooks := $(filter-out ../examples/save_image.ipynb, $(example_notebooks))
-
 example_names = $(foreach path, $(example_notebooks), $(basename $(notdir $(path))))
-example_htmls = $(foreach name, $(example_names), $(STATICDIR)/examples/$(name).html)
 example_rsts = $(foreach name, $(example_names), examples.$(name).rst)
 
-html: conf.py index.rst *.md README.rst trimesh.rst examples.md $(example_rsts) $(example_htmls) .deps
-	@$(SPHINXBUILD) -M html "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
-	touch "$(BUILDDIR)/html/.nojekyll"
+
+html: conf.py $(CONTENT)/index.rst trimesh.rst README.rst $(example_rsts) examples.rst .deps
+	@$(SPHINXBUILD) -M html "$(GENDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
 	echo "trimesh.org" > "$(BUILDDIR)/html/CNAME"
-	mv "$(BUILDDIR)/html/_static/examples" "$(BUILDDIR)/html/examples" || true
-	mv "$(BUILDDIR)/html/_static/images" "$(BUILDDIR)/html/images" || true
-	cp "$(STATICDIR)/favicon.ico" "$(BUILDDIR)/html/favicon.ico" || true
+	touch "$(BUILDDIR)/html/.nojekyll"
+	cp -R "$(STATICDIR)/images" "$(BUILDDIR)/html/images" || true
+	cp   "$(STATICDIR)/favicon.ico" "$(BUILDDIR)/html/favicon.ico" || true
 
 .deps: requirements.txt
 	$(PIP) install -r requirements.txt
 	$(PIP) freeze > .deps
+	mkdir -p $(GENDIR)
+	mkdir -p $(BUILDDIR)
+	cp conf.py $(CONTENT)/* $(GENDIR)
 
-$(STATICDIR)/examples/%.html: ../examples/%.ipynb .deps
-	mkdir -p "$(STATICDIR)/examples"
-	$(NBCONVERT) nbconvert --execute --to html --output $(abspath $@) $<
-
-examples.%.rst: $(STATICDIR)/examples/%.html examples.template 
-	$(PYTHON) -c "open('$@', 'w').write(open('examples.template').read().format(name='$(*F)', url='$<'))"
+examples.%.rst : ../examples/%.ipynb .deps
+	$(NBCONVERT) nbconvert --execute --to rst --output-dir $(GENDIR) $<
 
-examples.md: .deps
-	$(PYTHON) "examples.py"
+examples.rst: .deps
+	$(PYTHON) examples.py --source=../examples --target=$(GENDIR)/examples.rst
 
 trimesh.rst: .deps
-	$(SPHINXGEN) -eTf -t "$(TEMPLATESDIR)" -o "$(SOURCEDIR)" ../trimesh
+	$(SPHINXGEN) -eTf -t "$(TEMPLATESDIR)" -o "$(GENDIR)" ../trimesh
 
 README.rst: ../README.md .deps
-	pandoc --from=gfm --to=rst --output=README.rst ../README.md
+	pandoc --from=gfm --to=rst --output="$(GENDIR)/README.rst" ../README.md
 
 clean:
-	rm -rvf "$(BUILDDIR)" "$(STATICDIR)/examples" examples.*.rst trimesh*.rst .deps
+	rm -rvf "$(BUILDDIR)" "$(GENDIR)"  .deps

docs/conf.py

@@ -80,14 +80,12 @@ def abspath(rel):
 html_theme = "furo"
 
 # options for furo
-html_theme_options = {
-    "display_version": True,
-}
+html_theme_options = {}
 
 # 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_static_path = ["static"]
 html_logo = "images/trimesh-logo.png"
 
 # custom css

docs/guides/contributing.md docs/content/contributing.mddocs/guides/contributing.md renamed to docs/content/contributing.md

@@ -10,28 +10,28 @@ Install
 .. toctree::
    :maxdepth: 2
 
-   guides/install.md
-
-Examples
-==========
-.. toctree::
-   :maxdepth: 2
-	      
-   examples.md
+   install.md
 
 Contributing
 ==========  
 .. toctree::
    :maxdepth: 1
 
-   Contributing <guides/contributing.md>
+   Contributing <contributing.md>
 
 Docker
 ==========  
 .. toctree::
    :maxdepth: 1
 
-   Docker <guides/docker.md>
+   Docker <docker.md>
+   
+Examples
+==========
+.. toctree::
+   :maxdepth: 1
+	      
+   Examples <examples.rst>
 
 API Reference
 =============

docs/guides/docker.md docs/content/docker.mddocs/guides/docker.md renamed to docs/content/docker.md

@@ -2,11 +2,10 @@
 examples.py
 ------------
 
-Generate `examples.md` from the contents
+Convert `ipynb` to a web-renderable format from the contents
 of `../examples/*.ipynb`
 """
 
-import json
 import logging
 import os
 import sys
@@ -18,12 +17,6 @@
 # current working directory
 pwd = os.path.abspath(os.path.expanduser(os.path.dirname(__file__)))
 
-# where are our notebooks to render
-source = os.path.abspath(os.path.join(pwd, "..", "examples"))
-
-# which index file are we generating
-target = os.path.abspath(os.path.join(pwd, "examples.md"))
-
 
 def extract_docstring(loaded):
     """
@@ -50,27 +43,104 @@ def extract_docstring(loaded):
     return " ".join(i.strip() for i in source[1:-1])
 
 
-if __name__ == "__main__":
-    markdown = [
-        "# Examples",
+base = """
+{title} </{file_name}.html>
+"""
+
+
+def generate_index(source: str, target: str) -> str:
+    """
+    Go through a directory of source `ipynb` files and write
+    an RST index with a toctree.
+
+    Also postprocesses the results of `jupyter nbconvert`
+    """
+
+    lines = [
+        "Examples",
+        "===========",
         "Several examples are available as rendered IPython notebooks.",
         "",
+        ".. toctree::",
+        "   :maxdepth: 2",
+        "",
     ]
 
+    target_dir = os.path.dirname(target)
+
     for fn in os.listdir(source):
         if not fn.lower().endswith(".ipynb"):
             continue
-        path = os.path.join(source, fn)
-        with open(path) as f:
-            raw = json.load(f)
-        doc = extract_docstring(raw)
-        log.info(f'`{fn}`: "{doc}"\n')
-        link = f'examples.{fn.split(".")[0]}.html'
-
-        markdown.append(f"### [{fn}]({link})")
-        markdown.append(doc)
-        markdown.append("")
-
-    final = "\n".join(markdown)
+
+        name = fn.rsplit(".")[0]
+        title = name.replace("_", " ").title()
+        # notebook converted to RST
+        convert = os.path.join(target_dir, f"{name}.rst")
+        if not os.path.exists(convert):
+            print(f"no RST for {name}.rst")
+            continue
+
+        with open(convert) as f:
+            doc, post = postprocess(f.read(), title=title)
+        with open(convert, "w") as f:
+            f.write(post)
+
+        lines.append(f"   {name}")
+        # lines.append(doc)
+        lines.append("")
+
+    return "\n".join(lines)
+
+
+def postprocess(text: str, title: str) -> str:
+    """
+    Postprocess an RST generated from `jupyter nbconvert`
+    """
+    lines = str.splitlines(text)
+
+    # already has a title so exit
+    if "===" in "".join(lines[:4]):
+        return "", text
+
+    head = []
+    index = 0
+    ready = False
+    for i, L in enumerate(lines):
+        if "parsed-literal" in L:
+            ready = True
+            continue
+        if ready:
+            if "code::" in L:
+                index = i
+                break
+            else:
+                head.append(L)
+
+    # clean up the "parsed literal"
+    docstring = (
+        " ".join(" ".join(head).replace("\\n", " ").split()).strip().strip("'").strip()
+    )
+
+    # add a title and the docstring as a header
+    clip = f"{title}\n=============\n{docstring}\n\n" + "\n".join(lines[index:])
+
+    return docstring, clip
+
+
+if __name__ == "__main__":
+    import argparse
+
+    parser = argparse.ArgumentParser()
+    parser.add_argument(
+        "--source", type=str, help="a directory containing `ipynb` files", required=True
+    )
+    parser.add_argument(
+        "--target", type=str, help="Where the generated .rst file goes", required=True
+    )
+    args = parser.parse_args()
+
+    source = os.path.abspath(args.source)
+    target = os.path.abspath(args.target)
+
     with open(target, "w") as f:
-        f.write(final)
+        f.write(generate_index(source=source, target=target))