Add all examples to Sphinx docs #1082

py/Makefile

@@ -15,7 +15,7 @@ setup: ## Install dependencies
 	./venv/bin/python -m pip install --editable .
 
 .PHONY: docs
-docs: ## Build API docs
+docs: sync-examples ## Build API docs
 	./venv/bin/sphinx-build -b html docs build/docs
 
 docs-zip: docs ## Build and package docs into a zip file
@@ -29,6 +29,10 @@ examples:
 	sed -i -r -e "s/telesync.+/telesync==$(VERSION)/" examples/requirements.txt
 	tar -czf examples.tar.gz --exclude='*.state' --exclude='__pycache__' examples/
 
+sync-examples:
+	rm -f docs/example*.rst
+	./venv/bin/python docs/sync_examples.py
+
 clean: purge ## Clean
 	rm -rf docs/build telesync-api-docs.zip venv
 	rm -f examples.tar.gz

py/docs/.gitignore

@@ -0,0 +1 @@
+/example*.rst

py/docs/conf.py

@@ -13,16 +13,15 @@
 import os
 import sys
 import sphinx_rtd_theme
-sys.path.insert(0, os.path.abspath('..'))
 
+sys.path.insert(0, os.path.abspath('..'))
 
 # -- Project information -----------------------------------------------------
 
 project = 'Telesync'
 copyright = '2020, Prithvi Prabhu'
 author = 'Prithvi Prabhu'
 
-
 # -- General configuration ---------------------------------------------------
 
 # Add any Sphinx extension module names here, as strings. They can be
@@ -42,7 +41,6 @@
 # This pattern also affects html_static_path and html_extra_path.
 exclude_patterns = []
 
-
 # -- Options for HTML output -------------------------------------------------
 
 # The theme to use for HTML and HTML Help pages.  See the documentation for
@@ -53,7 +51,28 @@
 # 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']
 
+# These paths are either relative to html_static_path
+# or fully qualified paths (eg. https://...)
+# html_css_files = [
+#     'custom.css',
+# ]
 
 # -- Extension configuration -------------------------------------------------
+html_theme_options = {
+    # 'canonical_url': '',
+    # 'analytics_id': 'UA-XXXXXXX-1',  # Provided by Google in your dashboard
+    # 'logo_only': False,
+    # 'display_version': True,
+    # 'prev_next_buttons_location': 'bottom',
+    # 'style_external_links': False,
+    # 'vcs_pageview_mode': '',
+    # 'style_nav_header_background': 'white',
+    # # Toc options
+    'collapse_navigation': False,
+    # 'sticky_navigation': True,
+    # 'navigation_depth': 4,
+    # 'includehidden': True,
+    # 'titles_only': False
+}

py/docs/index.rst

@@ -6,6 +6,7 @@ Welcome to the Telesync API documentation!
    :caption: Contents:
 
    modules
+   examples
 
 Introduction
 ============

py/docs/modules.rst

@@ -1,5 +1,5 @@
-telesync
-========
+API
+===
 
 .. toctree::
    :maxdepth: 4

py/docs/sync_examples.py

@@ -0,0 +1,77 @@
+import os.path
+from typing import List
+
+index_content = '''
+Examples
+========
+
+.. toctree::
+   :maxdepth: 4
+
+'''
+
+docs_dir = os.path.realpath(os.path.dirname(__file__))
+example_dir = os.path.realpath(os.path.join(os.path.dirname(__file__), os.pardir, 'examples'))
+
+
+class Example:
+    def __init__(self, filename: str, title: str, description: str, code: str):
+        self.name = os.path.splitext(filename)[0]
+        self.filename = filename
+        self.title = title
+        self.description = description
+        self.code = code
+
+
+def read_lines(p: str) -> List[str]:
+    with open(p) as f:
+        return f.readlines()
+
+
+def read_file(p: str) -> str:
+    with open(p) as f:
+        return f.read()
+
+
+def write_file(p: str, txt: str) -> str:
+    with open(p, 'w') as f:
+        f.write(txt)
+    return txt
+
+
+def strip_comment(line: str) -> str:
+    return line.strip(" #")
+
+
+def load_example(filename: str) -> Example:
+    contents = read_file(os.path.join(example_dir, filename))
+    parts = contents.split('---', maxsplit=1)
+    header, code = parts[0].strip().splitlines(), parts[1].strip()
+    title, description = strip_comment(header[0]), [strip_comment(x) for x in header[1:]]
+    return Example(filename, title, '\n'.join(description), code)
+
+
+def main():
+    filenames = [line.strip() for line in read_lines(os.path.join(example_dir, 'tour.conf')) if
+                 not line.strip().startswith('#')]
+
+    examples = [load_example(filename) for filename in filenames]
+
+    examples_rst = [f'   example_{e.name}' for e in examples]
+    examples_rst.insert(0, index_content)
+    write_file(os.path.join(docs_dir, 'examples.rst'), '\n'.join(examples_rst))
+
+    for e in examples:
+        example_rst = [
+            e.title,
+            '=' * len(e.title),
+            '',
+            e.description,
+            '',
+            f'.. literalinclude:: ../examples/{e.name}.py',
+        ]
+        write_file(os.path.join(docs_dir, f'example_{e.name}.rst'), '\n'.join(example_rst))
+
+
+if __name__ == '__main__':
+    main()