Gabriel Somlo 9d8dcab
From 41978a7af0f4807c4dfa8d3dc794ac671540bf6e Mon Sep 17 00:00:00 2001
Gabriel Somlo 9d8dcab
From: "Gabriel L. Somlo" <gsomlo@gmail.com>
Gabriel Somlo 9d8dcab
Date: Tue, 1 Oct 2019 15:23:50 -0400
Gabriel Somlo 9d8dcab
Subject: [PATCH] Revert "Change theme to Sphinx Material Design"
Gabriel Somlo 9d8dcab
Gabriel Somlo 9d8dcab
This reverts commit de5eec38c4333eac947579d4c6b5695b3edb2499.
Gabriel Somlo 9d8dcab
Gabriel Somlo 9d8dcab
Reverting this change should allow building the PDF manual as
Gabriel Somlo 9d8dcab
part of a Fedora RPM package.
Gabriel Somlo 9d8dcab
Gabriel Somlo 9d8dcab
Signed-off-by: Gabriel Somlo <gsomlo@gmail.com>
Gabriel Somlo 9d8dcab
---
Gabriel Somlo 9d8dcab
 docs/.gitignore                |   1 -
Gabriel Somlo 9d8dcab
 docs/Makefile                  |  30 ++----
Gabriel Somlo 9d8dcab
 docs/_static/.keepme           |   0
Gabriel Somlo 9d8dcab
 docs/conf.py                   | 116 ++++-----------------
Gabriel Somlo 9d8dcab
 docs/markdown_code_symlinks.py | 179 +++++++++++++++++++++++++++++++++
Gabriel Somlo 9d8dcab
 docs/requirements.txt          |   7 +-
Gabriel Somlo 9d8dcab
 6 files changed, 209 insertions(+), 124 deletions(-)
Gabriel Somlo 9d8dcab
 delete mode 100644 docs/_static/.keepme
Gabriel Somlo 9d8dcab
 create mode 100644 docs/markdown_code_symlinks.py
Gabriel Somlo 9d8dcab
Gabriel Somlo 9d8dcab
diff --git a/docs/.gitignore b/docs/.gitignore
Gabriel Somlo 9d8dcab
index 13856a1..e35d885 100644
Gabriel Somlo 9d8dcab
--- a/docs/.gitignore
Gabriel Somlo 9d8dcab
+++ b/docs/.gitignore
Gabriel Somlo 9d8dcab
@@ -1,2 +1 @@
Gabriel Somlo 9d8dcab
-venv
Gabriel Somlo 9d8dcab
 _build
Gabriel Somlo 9d8dcab
diff --git a/docs/Makefile b/docs/Makefile
Gabriel Somlo 9d8dcab
index cb6f107..b52c668 100644
Gabriel Somlo 9d8dcab
--- a/docs/Makefile
Gabriel Somlo 9d8dcab
+++ b/docs/Makefile
Gabriel Somlo 9d8dcab
@@ -1,15 +1,13 @@
Gabriel Somlo 9d8dcab
 # Minimal makefile for Sphinx documentation
Gabriel Somlo 9d8dcab
 #
Gabriel Somlo 9d8dcab
 
Gabriel Somlo 9d8dcab
-MAKEDIR := $(dir $(lastword $(MAKEFILE_LIST)))
Gabriel Somlo 9d8dcab
-
Gabriel Somlo 9d8dcab
 # You can set these variables from the command line.
Gabriel Somlo 9d8dcab
-SPHINXOPTS      =
Gabriel Somlo 9d8dcab
-SPHINXBUILD     = [ -e venv/bin/activate ] && source venv/bin/activate; sphinx-build
Gabriel Somlo 9d8dcab
-SPHINXAUTOBUILD = [ -e venv/bin/activate ] && source venv/bin/activate; sphinx-autobuild
Gabriel Somlo 9d8dcab
-SPHINXPROJ      = ProjectTrellis
Gabriel Somlo 9d8dcab
-SOURCEDIR       = .
Gabriel Somlo 9d8dcab
-BUILDDIR        = _build
Gabriel Somlo 9d8dcab
+SPHINXOPTS    =
Gabriel Somlo 9d8dcab
+SPHINXBUILD   = sphinx-build
Gabriel Somlo 9d8dcab
+SPHINXAUTOBUILD   = sphinx-autobuild
Gabriel Somlo 9d8dcab
+SPHINXPROJ    = ProjectX-Ray
Gabriel Somlo 9d8dcab
+SOURCEDIR     = .
Gabriel Somlo 9d8dcab
+BUILDDIR      = _build
Gabriel Somlo 9d8dcab
 
Gabriel Somlo 9d8dcab
 # Put it first so that "make" without argument is like "make help".
Gabriel Somlo 9d8dcab
 help:
Gabriel Somlo 9d8dcab
@@ -18,21 +16,9 @@ help:
Gabriel Somlo 9d8dcab
 livehtml:
Gabriel Somlo 9d8dcab
 	@$(SPHINXAUTOBUILD) -b html --ignore \*.swp --ignore \*~ $(SPHINXOPTS) "$(SOURCEDIR)" "$(BUILDDIR)/html"
Gabriel Somlo 9d8dcab
 
Gabriel Somlo 9d8dcab
-.PHONY: help livehtml Makefile
Gabriel Somlo 9d8dcab
-
Gabriel Somlo 9d8dcab
-venv:
Gabriel Somlo 9d8dcab
-	rm -rf venv
Gabriel Somlo 9d8dcab
-	virtualenv --python=python3 venv
Gabriel Somlo 9d8dcab
-	source venv/bin/activate; pip install -r requirements.txt
Gabriel Somlo 9d8dcab
-
Gabriel Somlo 9d8dcab
-.PHONY: venv
Gabriel Somlo 9d8dcab
-
Gabriel Somlo 9d8dcab
-links:
Gabriel Somlo 9d8dcab
-	@true
Gabriel Somlo 9d8dcab
-
Gabriel Somlo 9d8dcab
-.PHONY: links
Gabriel Somlo 9d8dcab
+.PHONY: help livereload Makefile
Gabriel Somlo 9d8dcab
 
Gabriel Somlo 9d8dcab
 # Catch-all target: route all unknown targets to Sphinx using the new
Gabriel Somlo 9d8dcab
 # "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
Gabriel Somlo 9d8dcab
-%: Makefile links
Gabriel Somlo 9d8dcab
+%: Makefile
Gabriel Somlo 9d8dcab
 	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
Gabriel Somlo 9d8dcab
diff --git a/docs/_static/.keepme b/docs/_static/.keepme
Gabriel Somlo 9d8dcab
deleted file mode 100644
Gabriel Somlo 9d8dcab
index e69de29..0000000
Gabriel Somlo 9d8dcab
diff --git a/docs/conf.py b/docs/conf.py
Gabriel Somlo 9d8dcab
index e847b58..8989469 100644
Gabriel Somlo 9d8dcab
--- a/docs/conf.py
Gabriel Somlo 9d8dcab
+++ b/docs/conf.py
Gabriel Somlo 9d8dcab
@@ -24,7 +24,7 @@ import recommonmark
Gabriel Somlo 9d8dcab
 import os
Gabriel Somlo 9d8dcab
 import sys
Gabriel Somlo 9d8dcab
 sys.path.insert(0, os.path.abspath('.'))
Gabriel Somlo 9d8dcab
-from markdown_code_symlinks import LinkParser, MarkdownSymlinksDomain
Gabriel Somlo 9d8dcab
+from markdown_code_symlinks import MarkdownCodeSymlinks
Gabriel Somlo 9d8dcab
 
Gabriel Somlo 9d8dcab
 # -- General configuration ------------------------------------------------
Gabriel Somlo 9d8dcab
 
Gabriel Somlo 9d8dcab
@@ -36,13 +36,8 @@ from markdown_code_symlinks import LinkParser, MarkdownSymlinksDomain
Gabriel Somlo 9d8dcab
 # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
Gabriel Somlo 9d8dcab
 # ones.
Gabriel Somlo 9d8dcab
 extensions = [
Gabriel Somlo 9d8dcab
-    'sphinx.ext.autodoc',
Gabriel Somlo 9d8dcab
-    'sphinx.ext.autosummary',
Gabriel Somlo 9d8dcab
-    'sphinx.ext.doctest',
Gabriel Somlo 9d8dcab
-    'sphinx.ext.imgmath',
Gabriel Somlo 9d8dcab
-    'sphinx.ext.napoleon',
Gabriel Somlo 9d8dcab
-    'sphinx.ext.todo',
Gabriel Somlo 9d8dcab
-    'sphinx_markdown_tables',
Gabriel Somlo 9d8dcab
+    'sphinx.ext.imgmath', 'sphinx.ext.autodoc', 'sphinx.ext.doctest',
Gabriel Somlo 9d8dcab
+    'sphinx.ext.autosummary', 'sphinx.ext.napoleon', 'sphinx.ext.todo'
Gabriel Somlo 9d8dcab
 ]
Gabriel Somlo 9d8dcab
 
Gabriel Somlo 9d8dcab
 # Add any paths that contain templates here, relative to this directory.
Gabriel Somlo 9d8dcab
@@ -52,7 +47,7 @@ templates_path = ['_templates']
Gabriel Somlo 9d8dcab
 # You can specify multiple suffix as a list of string:
Gabriel Somlo 9d8dcab
 source_suffix = ['.rst', '.md']
Gabriel Somlo 9d8dcab
 source_parsers = {
Gabriel Somlo 9d8dcab
-    '.md': 'markdown_code_symlinks.LinkParser',
Gabriel Somlo 9d8dcab
+    '.md': 'recommonmark.parser.CommonMarkParser',
Gabriel Somlo 9d8dcab
 }
Gabriel Somlo 9d8dcab
 
Gabriel Somlo 9d8dcab
 # The master toctree document.
Gabriel Somlo 9d8dcab
@@ -63,24 +58,6 @@ project = u'Project Trellis'
Gabriel Somlo 9d8dcab
 copyright = u'2018, SymbiFlow Team'
Gabriel Somlo 9d8dcab
 author = u'SymbiFlow Team'
Gabriel Somlo 9d8dcab
 
Gabriel Somlo 9d8dcab
-# Enable github links when not on readthedocs
Gabriel Somlo 9d8dcab
-on_rtd = os.environ.get('READTHEDOCS', None) == 'True'
Gabriel Somlo 9d8dcab
-if not on_rtd:
Gabriel Somlo 9d8dcab
-    html_context = {
Gabriel Somlo 9d8dcab
-        "display_github": True,  # Integrate GitHub
Gabriel Somlo 9d8dcab
-        "github_user": "symbiflow",  # Username
Gabriel Somlo 9d8dcab
-        "github_repo": "prjtrellis",  # Repo name
Gabriel Somlo 9d8dcab
-        "github_version": "master",  # Version
Gabriel Somlo 9d8dcab
-        "conf_py_path": "/doc/",
Gabriel Somlo 9d8dcab
-    }
Gabriel Somlo 9d8dcab
-else:
Gabriel Somlo 9d8dcab
-    docs_dir = os.path.abspath(os.path.dirname(__file__))
Gabriel Somlo 9d8dcab
-    print("Docs dir is:", docs_dir)
Gabriel Somlo 9d8dcab
-    import subprocess
Gabriel Somlo 9d8dcab
-    subprocess.call('git fetch origin --unshallow', cwd=docs_dir, shell=True)
Gabriel Somlo 9d8dcab
-    subprocess.check_call('git fetch origin --tags', cwd=docs_dir, shell=True)
Gabriel Somlo 9d8dcab
-    subprocess.check_call('make links', cwd=docs_dir, shell=True)
Gabriel Somlo 9d8dcab
-
Gabriel Somlo 9d8dcab
 # The version info for the project you're documenting, acts as replacement for
Gabriel Somlo 9d8dcab
 # |version| and |release|, also used in various other places throughout the
Gabriel Somlo 9d8dcab
 # built documents.
Gabriel Somlo 9d8dcab
@@ -100,10 +77,10 @@ language = None
Gabriel Somlo 9d8dcab
 # List of patterns, relative to source directory, that match files and
Gabriel Somlo 9d8dcab
 # directories to ignore when looking for source files.
Gabriel Somlo 9d8dcab
 # This patterns also effect to html_static_path and html_extra_path
Gabriel Somlo 9d8dcab
-exclude_patterns = ['_build', 'venv', 'Thumbs.db', '.DS_Store']
Gabriel Somlo 9d8dcab
+exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store']
Gabriel Somlo 9d8dcab
 
Gabriel Somlo 9d8dcab
 # The name of the Pygments (syntax highlighting) style to use.
Gabriel Somlo 9d8dcab
-pygments_style = 'default'
Gabriel Somlo 9d8dcab
+pygments_style = 'sphinx'
Gabriel Somlo 9d8dcab
 
Gabriel Somlo 9d8dcab
 # If true, `todo` and `todoList` produce output, else they produce nothing.
Gabriel Somlo 9d8dcab
 todo_include_todos = True
Gabriel Somlo 9d8dcab
@@ -113,67 +90,24 @@ todo_include_todos = True
Gabriel Somlo 9d8dcab
 # The theme to use for HTML and HTML Help pages.  See the documentation for
Gabriel Somlo 9d8dcab
 # a list of builtin themes.
Gabriel Somlo 9d8dcab
 #
Gabriel Somlo 9d8dcab
-html_theme = 'sphinx_materialdesign_theme'
Gabriel Somlo 9d8dcab
+html_theme = 'sphinx_rtd_theme'
Gabriel Somlo 9d8dcab
 
Gabriel Somlo 9d8dcab
 # Theme options are theme-specific and customize the look and feel of a theme
Gabriel Somlo 9d8dcab
 # further.  For a list of options available for each theme, see the
Gabriel Somlo 9d8dcab
 # documentation.
Gabriel Somlo 9d8dcab
 #
Gabriel Somlo 9d8dcab
-html_theme_options = {
Gabriel Somlo 9d8dcab
-    # Specify a list of menu in Header.
Gabriel Somlo 9d8dcab
-    # Tuples forms:
Gabriel Somlo 9d8dcab
-    #  ('Name', 'external url or path of pages in the document', boolean, 'icon name')
Gabriel Somlo 9d8dcab
-    #
Gabriel Somlo 9d8dcab
-    # Third argument:
Gabriel Somlo 9d8dcab
-    # True indicates an external link.
Gabriel Somlo 9d8dcab
-    # False indicates path of pages in the document.
Gabriel Somlo 9d8dcab
-    #
Gabriel Somlo 9d8dcab
-    # Fourth argument:
Gabriel Somlo 9d8dcab
-    # Specify the icon name.
Gabriel Somlo 9d8dcab
-    # For details see link.
Gabriel Somlo 9d8dcab
-    # https://material.io/icons/
Gabriel Somlo 9d8dcab
-    'header_links': [
Gabriel Somlo 9d8dcab
-        ('Home', 'index', False, 'home'),
Gabriel Somlo 9d8dcab
-        ("GitHub", "https://github.com/SymbiFlow/prjtrellis", True, 'link')
Gabriel Somlo 9d8dcab
-    ],
Gabriel Somlo 9d8dcab
+# html_theme_options = {}
Gabriel Somlo 9d8dcab
 
Gabriel Somlo 9d8dcab
-    # Customize css colors.
Gabriel Somlo 9d8dcab
-    # For details see link.
Gabriel Somlo 9d8dcab
-    # https://getmdl.io/customize/index.html
Gabriel Somlo 9d8dcab
-    #
Gabriel Somlo 9d8dcab
-    # Values: amber, blue, brown, cyan deep_orange, deep_purple, green, grey, indigo, light_blue,
Gabriel Somlo 9d8dcab
-    #         light_green, lime, orange, pink, purple, red, teal, yellow(Default: indigo)
Gabriel Somlo 9d8dcab
-    'primary_color':
Gabriel Somlo 9d8dcab
-    'deep_purple',
Gabriel Somlo 9d8dcab
-    # Values: Same as primary_color. (Default: pink)
Gabriel Somlo 9d8dcab
-    'accent_color':
Gabriel Somlo 9d8dcab
-    'purple',
Gabriel Somlo 9d8dcab
-
Gabriel Somlo 9d8dcab
-    # Customize layout.
Gabriel Somlo 9d8dcab
-    # For details see link.
Gabriel Somlo 9d8dcab
-    # https://getmdl.io/components/index.html#layout-section
Gabriel Somlo 9d8dcab
-    'fixed_drawer':
Gabriel Somlo 9d8dcab
-    True,
Gabriel Somlo 9d8dcab
-    'fixed_header':
Gabriel Somlo 9d8dcab
-    True,
Gabriel Somlo 9d8dcab
-    'header_waterfall':
Gabriel Somlo 9d8dcab
-    True,
Gabriel Somlo 9d8dcab
-    'header_scroll':
Gabriel Somlo 9d8dcab
-    False,
Gabriel Somlo 9d8dcab
-
Gabriel Somlo 9d8dcab
-    # Render title in header.
Gabriel Somlo 9d8dcab
-    # Values: True, False (Default: False)
Gabriel Somlo 9d8dcab
-    'show_header_title':
Gabriel Somlo 9d8dcab
-    False,
Gabriel Somlo 9d8dcab
-    # Render title in drawer.
Gabriel Somlo 9d8dcab
-    # Values: True, False (Default: True)
Gabriel Somlo 9d8dcab
-    'show_drawer_title':
Gabriel Somlo 9d8dcab
-    True,
Gabriel Somlo 9d8dcab
-    # Render footer.
Gabriel Somlo 9d8dcab
-    # Values: True, False (Default: True)
Gabriel Somlo 9d8dcab
-    'show_footer':
Gabriel Somlo 9d8dcab
-    True
Gabriel Somlo 9d8dcab
-}
Gabriel Somlo 9d8dcab
+# Enable github links when not on readthedocs
Gabriel Somlo 9d8dcab
+on_rtd = os.environ.get('READTHEDOCS', None) == 'True'
Gabriel Somlo 9d8dcab
+if not on_rtd:
Gabriel Somlo 9d8dcab
+    html_context = {
Gabriel Somlo 9d8dcab
+        "display_github": True,  # Integrate GitHub
Gabriel Somlo 9d8dcab
+        "github_user": "symbiflow",  # Username
Gabriel Somlo 9d8dcab
+        "github_repo": "prjtrellis",  # Repo name
Gabriel Somlo 9d8dcab
+        "github_version": "master",  # Version
Gabriel Somlo 9d8dcab
+        "conf_py_path": "/doc/",
Gabriel Somlo 9d8dcab
+    }
Gabriel Somlo 9d8dcab
 
Gabriel Somlo 9d8dcab
 # Add any paths that contain custom static files (such as style sheets) here,
Gabriel Somlo 9d8dcab
 # relative to this directory. They are copied after the builtin static files,
Gabriel Somlo 9d8dcab
@@ -250,17 +184,9 @@ intersphinx_mapping = {'https://docs.python.org/': None}
Gabriel Somlo 9d8dcab
 
Gabriel Somlo 9d8dcab
 
Gabriel Somlo 9d8dcab
 def setup(app):
Gabriel Somlo 9d8dcab
-    github_code_repo = 'https://github.com/SymbiFlow/prjtrellis/'
Gabriel Somlo 9d8dcab
-    github_code_branch = 'blob/master/'
Gabriel Somlo 9d8dcab
-
Gabriel Somlo 9d8dcab
-    docs_root_dir = os.path.realpath(os.path.dirname(__file__))
Gabriel Somlo 9d8dcab
-    code_root_dir = os.path.realpath(os.path.join(docs_root_dir, ".."))
Gabriel Somlo 9d8dcab
-
Gabriel Somlo 9d8dcab
-    MarkdownSymlinksDomain.init_domain(
Gabriel Somlo 9d8dcab
-        github_code_repo, github_code_branch, docs_root_dir, code_root_dir)
Gabriel Somlo 9d8dcab
-    MarkdownSymlinksDomain.find_links()
Gabriel Somlo 9d8dcab
-    app.add_domain(MarkdownSymlinksDomain)
Gabriel Somlo 9d8dcab
+    MarkdownCodeSymlinks.find_links()
Gabriel Somlo 9d8dcab
     app.add_config_value(
Gabriel Somlo 9d8dcab
         'recommonmark_config', {
Gabriel Somlo 9d8dcab
-            'github_code_repo': github_code_repo,
Gabriel Somlo 9d8dcab
+            'github_code_repo': 'https://github.com/SymbiFlow/prjtrellis',
Gabriel Somlo 9d8dcab
         }, True)
Gabriel Somlo 9d8dcab
+    app.add_transform(MarkdownCodeSymlinks)
Gabriel Somlo 9d8dcab
diff --git a/docs/markdown_code_symlinks.py b/docs/markdown_code_symlinks.py
Gabriel Somlo 9d8dcab
new file mode 100644
Gabriel Somlo 9d8dcab
index 0000000..1955493
Gabriel Somlo 9d8dcab
--- /dev/null
Gabriel Somlo 9d8dcab
+++ b/docs/markdown_code_symlinks.py
Gabriel Somlo 9d8dcab
@@ -0,0 +1,179 @@
Gabriel Somlo 9d8dcab
+import logging
Gabriel Somlo 9d8dcab
+import os
Gabriel Somlo 9d8dcab
+
Gabriel Somlo 9d8dcab
+from recommonmark import transform
Gabriel Somlo 9d8dcab
+"""
Gabriel Somlo 9d8dcab
+Allow linking of Markdown documentation from the source code tree into the Sphinx
Gabriel Somlo 9d8dcab
+documentation tree.
Gabriel Somlo 9d8dcab
+
Gabriel Somlo 9d8dcab
+The Markdown documents will have links relative to the source code root, rather
Gabriel Somlo 9d8dcab
+than the place they are now linked too - this code fixes these paths up.
Gabriel Somlo 9d8dcab
+
Gabriel Somlo 9d8dcab
+We also want links from two Markdown documents found in the Sphinx docs to
Gabriel Somlo 9d8dcab
+work, so that is also fixed up.
Gabriel Somlo 9d8dcab
+"""
Gabriel Somlo 9d8dcab
+
Gabriel Somlo 9d8dcab
+
Gabriel Somlo 9d8dcab
+def path_contains(parent_path, child_path):
Gabriel Somlo 9d8dcab
+    """Check a path contains another path.
Gabriel Somlo 9d8dcab
+
Gabriel Somlo 9d8dcab
+    >>> path_contains("a/b", "a/b")
Gabriel Somlo 9d8dcab
+    True
Gabriel Somlo 9d8dcab
+    >>> path_contains("a/b", "a/b/")
Gabriel Somlo 9d8dcab
+    True
Gabriel Somlo 9d8dcab
+    >>> path_contains("a/b", "a/b/c")
Gabriel Somlo 9d8dcab
+    True
Gabriel Somlo 9d8dcab
+    >>> path_contains("a/b", "c")
Gabriel Somlo 9d8dcab
+    False
Gabriel Somlo 9d8dcab
+    >>> path_contains("a/b", "c/b")
Gabriel Somlo 9d8dcab
+    False
Gabriel Somlo 9d8dcab
+    >>> path_contains("a/b", "c/../a/b/d")
Gabriel Somlo 9d8dcab
+    True
Gabriel Somlo 9d8dcab
+    >>> path_contains("../a/b", "../a/b/d")
Gabriel Somlo 9d8dcab
+    True
Gabriel Somlo 9d8dcab
+    >>> path_contains("../a/b", "../a/c")
Gabriel Somlo 9d8dcab
+    False
Gabriel Somlo 9d8dcab
+    >>> path_contains("a", "abc")
Gabriel Somlo 9d8dcab
+    False
Gabriel Somlo 9d8dcab
+    >>> path_contains("aa", "abc")
Gabriel Somlo 9d8dcab
+    False
Gabriel Somlo 9d8dcab
+    """
Gabriel Somlo 9d8dcab
+    # Append a separator to the end of both paths to work around the fact that
Gabriel Somlo 9d8dcab
+    # os.path.commonprefix does character by character comparisons rather than
Gabriel Somlo 9d8dcab
+    # path segment by path segment.
Gabriel Somlo 9d8dcab
+    parent_path = os.path.join(os.path.normpath(parent_path), '')
Gabriel Somlo 9d8dcab
+    child_path = os.path.join(os.path.normpath(child_path), '')
Gabriel Somlo 9d8dcab
+    common_path = os.path.commonprefix((parent_path, child_path))
Gabriel Somlo 9d8dcab
+    return common_path == parent_path
Gabriel Somlo 9d8dcab
+
Gabriel Somlo 9d8dcab
+
Gabriel Somlo 9d8dcab
+def relative(parent_dir, child_path):
Gabriel Somlo 9d8dcab
+    """Get the relative between a path that contains another path."""
Gabriel Somlo 9d8dcab
+    child_dir = os.path.dirname(child_path)
Gabriel Somlo 9d8dcab
+    assert path_contains(parent_dir, child_dir), "{} not inside {}".format(
Gabriel Somlo 9d8dcab
+        child_path, parent_dir)
Gabriel Somlo 9d8dcab
+    return os.path.relpath(child_path, start=parent_dir)
Gabriel Somlo 9d8dcab
+
Gabriel Somlo 9d8dcab
+
Gabriel Somlo 9d8dcab
+class MarkdownCodeSymlinks(transform.AutoStructify, object):
Gabriel Somlo 9d8dcab
+    docs_root_dir = os.path.realpath(os.path.dirname(__file__))
Gabriel Somlo 9d8dcab
+    code_root_dir = os.path.realpath(os.path.join(docs_root_dir, "..", ".."))
Gabriel Somlo 9d8dcab
+
Gabriel Somlo 9d8dcab
+    mapping = {
Gabriel Somlo 9d8dcab
+        'docs2code': {},
Gabriel Somlo 9d8dcab
+        'code2docs': {},
Gabriel Somlo 9d8dcab
+    }
Gabriel Somlo 9d8dcab
+
Gabriel Somlo 9d8dcab
+    @classmethod
Gabriel Somlo 9d8dcab
+    def relative_code(cls, url):
Gabriel Somlo 9d8dcab
+        """Get a value relative to the code directory."""
Gabriel Somlo 9d8dcab
+        return relative(cls.code_root_dir, url)
Gabriel Somlo 9d8dcab
+
Gabriel Somlo 9d8dcab
+    @classmethod
Gabriel Somlo 9d8dcab
+    def relative_docs(cls, url):
Gabriel Somlo 9d8dcab
+        """Get a value relative to the docs directory."""
Gabriel Somlo 9d8dcab
+        return relative(cls.docs_root_dir, url)
Gabriel Somlo 9d8dcab
+
Gabriel Somlo 9d8dcab
+    @classmethod
Gabriel Somlo 9d8dcab
+    def add_mapping(cls, docs_rel, code_rel):
Gabriel Somlo 9d8dcab
+        assert docs_rel not in cls.mapping['docs2code'], """\
Gabriel Somlo 9d8dcab
+Assertion error! Document already in mapping!
Gabriel Somlo 9d8dcab
+    New Value: {}
Gabriel Somlo 9d8dcab
+Current Value: {}
Gabriel Somlo 9d8dcab
+""".format(docs_rel, cls.mapping['docs2code'][docs_rel])
Gabriel Somlo 9d8dcab
+        assert code_rel not in cls.mapping['code2docs'], """\
Gabriel Somlo 9d8dcab
+Assertion error! Document already in mapping!
Gabriel Somlo 9d8dcab
+    New Value: {}
Gabriel Somlo 9d8dcab
+Current Value: {}
Gabriel Somlo 9d8dcab
+""".format(docs_rel, cls.mapping['code2docs'][code_rel])
Gabriel Somlo 9d8dcab
+
Gabriel Somlo 9d8dcab
+        cls.mapping['docs2code'][docs_rel] = code_rel
Gabriel Somlo 9d8dcab
+        cls.mapping['code2docs'][code_rel] = docs_rel
Gabriel Somlo 9d8dcab
+
Gabriel Somlo 9d8dcab
+    @classmethod
Gabriel Somlo 9d8dcab
+    def find_links(cls):
Gabriel Somlo 9d8dcab
+        """Walk the docs dir and find links to docs in the code dir."""
Gabriel Somlo 9d8dcab
+        for root, dirs, files in os.walk(cls.docs_root_dir):
Gabriel Somlo 9d8dcab
+            for fname in files:
Gabriel Somlo 9d8dcab
+                fpath = os.path.abspath(os.path.join(root, fname))
Gabriel Somlo 9d8dcab
+
Gabriel Somlo 9d8dcab
+                if not os.path.islink(fpath):
Gabriel Somlo 9d8dcab
+                    continue
Gabriel Somlo 9d8dcab
+
Gabriel Somlo 9d8dcab
+                link_path = os.path.join(root, os.readlink(fpath))
Gabriel Somlo 9d8dcab
+                # Is link outside the code directory?
Gabriel Somlo 9d8dcab
+                if not path_contains(cls.code_root_dir, link_path):
Gabriel Somlo 9d8dcab
+                    continue
Gabriel Somlo 9d8dcab
+
Gabriel Somlo 9d8dcab
+                # Is link internal to the docs directory?
Gabriel Somlo 9d8dcab
+                if path_contains(cls.docs_root_dir, link_path):
Gabriel Somlo 9d8dcab
+                    continue
Gabriel Somlo 9d8dcab
+
Gabriel Somlo 9d8dcab
+                docs_rel = cls.relative_docs(fpath)
Gabriel Somlo 9d8dcab
+                code_rel = cls.relative_code(link_path)
Gabriel Somlo 9d8dcab
+
Gabriel Somlo 9d8dcab
+                cls.add_mapping(docs_rel, code_rel)
Gabriel Somlo 9d8dcab
+        import pprint
Gabriel Somlo 9d8dcab
+        pprint.pprint(cls.mapping)
Gabriel Somlo 9d8dcab
+
Gabriel Somlo 9d8dcab
+    @property
Gabriel Somlo 9d8dcab
+    def url_resolver(self):
Gabriel Somlo 9d8dcab
+        return self._url_resolver
Gabriel Somlo 9d8dcab
+
Gabriel Somlo 9d8dcab
+    @url_resolver.setter
Gabriel Somlo 9d8dcab
+    def url_resolver(self, value):
Gabriel Somlo 9d8dcab
+        print(self, value)
Gabriel Somlo 9d8dcab
+
Gabriel Somlo 9d8dcab
+    # Resolve a link from one markdown to another document.
Gabriel Somlo 9d8dcab
+    def _url_resolver(self, ourl):
Gabriel Somlo 9d8dcab
+        """Resolve a URL found in a markdown file."""
Gabriel Somlo 9d8dcab
+        assert self.docs_root_dir == os.path.realpath(self.root_dir), """\
Gabriel Somlo 9d8dcab
+Configuration error! Document Root != Current Root
Gabriel Somlo 9d8dcab
+Document Root: {}
Gabriel Somlo 9d8dcab
+ Current Root: {}
Gabriel Somlo 9d8dcab
+""".format(self.docs_root_dir, self.root_dir)
Gabriel Somlo 9d8dcab
+
Gabriel Somlo 9d8dcab
+        src_path = os.path.abspath(self.document['source'])
Gabriel Somlo 9d8dcab
+        src_dir = os.path.dirname(src_path)
Gabriel Somlo 9d8dcab
+        dst_path = os.path.abspath(os.path.join(self.docs_root_dir, ourl))
Gabriel Somlo 9d8dcab
+        dst_rsrc = os.path.relpath(dst_path, start=src_dir)
Gabriel Somlo 9d8dcab
+
Gabriel Somlo 9d8dcab
+        src_rdoc = self.relative_docs(src_path)
Gabriel Somlo 9d8dcab
+
Gabriel Somlo 9d8dcab
+        print
Gabriel Somlo 9d8dcab
+        print("url_resolver")
Gabriel Somlo 9d8dcab
+        print(src_path)
Gabriel Somlo 9d8dcab
+        print(dst_path)
Gabriel Somlo 9d8dcab
+        print(dst_rsrc)
Gabriel Somlo 9d8dcab
+        print(src_rdoc)
Gabriel Somlo 9d8dcab
+
Gabriel Somlo 9d8dcab
+        # Is the source document a linked one?
Gabriel Somlo 9d8dcab
+        if src_rdoc not in self.mapping['docs2code']:
Gabriel Somlo 9d8dcab
+            # Don't do any rewriting on non-linked markdown.
Gabriel Somlo 9d8dcab
+            url = ourl
Gabriel Somlo 9d8dcab
+
Gabriel Somlo 9d8dcab
+        # Is the destination also inside docs?
Gabriel Somlo 9d8dcab
+        elif dst_rsrc not in self.mapping['code2docs']:
Gabriel Somlo 9d8dcab
+            # Return a path to the GitHub repo.
Gabriel Somlo 9d8dcab
+            url = "{}/blob/master/{}".format(
Gabriel Somlo 9d8dcab
+                self.config['github_code_repo'], dst_rsrc)
Gabriel Somlo 9d8dcab
+        else:
Gabriel Somlo 9d8dcab
+            url = os.path.relpath(
Gabriel Somlo 9d8dcab
+                os.path.join(
Gabriel Somlo 9d8dcab
+                    self.docs_root_dir, self.mapping['code2docs'][dst_rsrc]),
Gabriel Somlo 9d8dcab
+                start=src_dir)
Gabriel Somlo 9d8dcab
+            base_url, ext = os.path.splitext(url)
Gabriel Somlo 9d8dcab
+            assert ext in (".md",
Gabriel Somlo 9d8dcab
+                           ".markdown"), ("Unknown extension {}".format(ext))
Gabriel Somlo 9d8dcab
+            url = "{}.html".format(base_url)
Gabriel Somlo 9d8dcab
+
Gabriel Somlo 9d8dcab
+        print("---")
Gabriel Somlo 9d8dcab
+        print(ourl)
Gabriel Somlo 9d8dcab
+        print(url)
Gabriel Somlo 9d8dcab
+        print
Gabriel Somlo 9d8dcab
+        return url
Gabriel Somlo 9d8dcab
+
Gabriel Somlo 9d8dcab
+
Gabriel Somlo 9d8dcab
+if __name__ == "__main__":
Gabriel Somlo 9d8dcab
+    import doctest
Gabriel Somlo 9d8dcab
+    doctest.testmod()
Gabriel Somlo 9d8dcab
diff --git a/docs/requirements.txt b/docs/requirements.txt
Gabriel Somlo 9d8dcab
index ec9e872..56c1f78 100644
Gabriel Somlo 9d8dcab
--- a/docs/requirements.txt
Gabriel Somlo 9d8dcab
+++ b/docs/requirements.txt
Gabriel Somlo 9d8dcab
@@ -1,13 +1,8 @@
Gabriel Somlo 9d8dcab
-sphinx_materialdesign_theme
Gabriel Somlo 9d8dcab
-
Gabriel Somlo 9d8dcab
 docutils
Gabriel Somlo 9d8dcab
 sphinx
Gabriel Somlo 9d8dcab
 sphinx-autobuild
Gabriel Somlo 9d8dcab
 
Gabriel Somlo 9d8dcab
 breathe
Gabriel Somlo 9d8dcab
 recommonmark
Gabriel Somlo 9d8dcab
-sphinx-markdown-tables
Gabriel Somlo 9d8dcab
+sphinx_rtd_theme
Gabriel Somlo 9d8dcab
 sphinxcontrib-napoleon
Gabriel Somlo 9d8dcab
-
Gabriel Somlo 9d8dcab
-# Markdown cross-reference solver library
Gabriel Somlo 9d8dcab
-git+https://github.com/SymbiFlow/sphinxcontrib-markdown-symlinks
Gabriel Somlo 9d8dcab
-- 
Gabriel Somlo 9d8dcab
2.21.0
Gabriel Somlo 9d8dcab