From 41978a7af0f4807c4dfa8d3dc794ac671540bf6e Mon Sep 17 00:00:00 2001

From: "Gabriel L. Somlo" <gsomlo@gmail.com>

Date: Tue, 1 Oct 2019 15:23:50 -0400

Subject: [PATCH] Revert "Change theme to Sphinx Material Design"

This reverts commit de5eec38c4333eac947579d4c6b5695b3edb2499.

Reverting this change should allow building the PDF manual as

part of a Fedora RPM package.

Signed-off-by: Gabriel Somlo <gsomlo@gmail.com>

---

 docs/.gitignore                |   1 -

 docs/Makefile                  |  30 ++----

 docs/_static/.keepme           |   0

 docs/conf.py                   | 116 ++++-----------------

 docs/markdown_code_symlinks.py | 179 +++++++++++++++++++++++++++++++++

 docs/requirements.txt          |   7 +-

 6 files changed, 209 insertions(+), 124 deletions(-)

 delete mode 100644 docs/_static/.keepme

 create mode 100644 docs/markdown_code_symlinks.py

diff --git a/docs/.gitignore b/docs/.gitignore

index 13856a1..e35d885 100644

--- a/docs/.gitignore

+++ b/docs/.gitignore

@@ -1,2 +1 @@

-venv

 _build

diff --git a/docs/Makefile b/docs/Makefile

index cb6f107..b52c668 100644

--- a/docs/Makefile

+++ b/docs/Makefile

@@ -1,15 +1,13 @@

 # Minimal makefile for Sphinx documentation

 #

-MAKEDIR := $(dir $(lastword $(MAKEFILE_LIST)))

-

 # You can set these variables from the command line.

-SPHINXOPTS      =

-SPHINXBUILD     = [ -e venv/bin/activate ] && source venv/bin/activate; sphinx-build

-SPHINXAUTOBUILD = [ -e venv/bin/activate ] && source venv/bin/activate; sphinx-autobuild

-SPHINXPROJ      = ProjectTrellis

-SOURCEDIR       = .

-BUILDDIR        = _build

+SPHINXOPTS    =

+SPHINXBUILD   = sphinx-build

+SPHINXAUTOBUILD   = sphinx-autobuild

+SPHINXPROJ    = ProjectX-Ray

+SOURCEDIR     = .

+BUILDDIR      = _build

 # Put it first so that "make" without argument is like "make help".

 help:

@@ -18,21 +16,9 @@ help:

 livehtml:

 	@$(SPHINXAUTOBUILD) -b html --ignore \*.swp --ignore \*~ $(SPHINXOPTS) "$(SOURCEDIR)" "$(BUILDDIR)/html"

-.PHONY: help livehtml Makefile

-

-venv:

-	rm -rf venv

-	virtualenv --python=python3 venv

-	source venv/bin/activate; pip install -r requirements.txt

-

-.PHONY: venv

-

-links:

-	@true

-

-.PHONY: links

+.PHONY: help livereload 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 links

+%: Makefile

 	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)

diff --git a/docs/_static/.keepme b/docs/_static/.keepme

deleted file mode 100644

index e69de29..0000000

diff --git a/docs/conf.py b/docs/conf.py

index e847b58..8989469 100644

--- a/docs/conf.py

+++ b/docs/conf.py

@@ -24,7 +24,7 @@ import recommonmark

 import os

 import sys

 sys.path.insert(0, os.path.abspath('.'))

-from markdown_code_symlinks import LinkParser, MarkdownSymlinksDomain

+from markdown_code_symlinks import MarkdownCodeSymlinks

 # -- General configuration ------------------------------------------------

@@ -36,13 +36,8 @@ from markdown_code_symlinks import LinkParser, MarkdownSymlinksDomain

 # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom

 # ones.

 extensions = [

-    'sphinx.ext.autodoc',

-    'sphinx.ext.autosummary',

-    'sphinx.ext.doctest',

-    'sphinx.ext.imgmath',

-    'sphinx.ext.napoleon',

-    'sphinx.ext.todo',

-    'sphinx_markdown_tables',

+    'sphinx.ext.imgmath', 'sphinx.ext.autodoc', 'sphinx.ext.doctest',

+    'sphinx.ext.autosummary', 'sphinx.ext.napoleon', 'sphinx.ext.todo'

 ]

 # Add any paths that contain templates here, relative to this directory.

@@ -52,7 +47,7 @@ templates_path = ['_templates']

 # You can specify multiple suffix as a list of string:

 source_suffix = ['.rst', '.md']

 source_parsers = {

-    '.md': 'markdown_code_symlinks.LinkParser',

+    '.md': 'recommonmark.parser.CommonMarkParser',

 }

 # The master toctree document.

@@ -63,24 +58,6 @@ project = u'Project Trellis'

 copyright = u'2018, SymbiFlow Team'

 author = u'SymbiFlow Team'

-# Enable github links when not on readthedocs

-on_rtd = os.environ.get('READTHEDOCS', None) == 'True'

-if not on_rtd:

-    html_context = {

-        "display_github": True,  # Integrate GitHub

-        "github_user": "symbiflow",  # Username

-        "github_repo": "prjtrellis",  # Repo name

-        "github_version": "master",  # Version

-        "conf_py_path": "/doc/",

-    }

-else:

-    docs_dir = os.path.abspath(os.path.dirname(__file__))

-    print("Docs dir is:", docs_dir)

-    import subprocess

-    subprocess.call('git fetch origin --unshallow', cwd=docs_dir, shell=True)

-    subprocess.check_call('git fetch origin --tags', cwd=docs_dir, shell=True)

-    subprocess.check_call('make links', cwd=docs_dir, shell=True)

-

 # The version info for the project you're documenting, acts as replacement for

 # |version| and |release|, also used in various other places throughout the

 # built documents.

@@ -100,10 +77,10 @@ language = None

 # List of patterns, relative to source directory, that match files and

 # directories to ignore when looking for source files.

 # This patterns also effect to html_static_path and html_extra_path

-exclude_patterns = ['_build', 'venv', 'Thumbs.db', '.DS_Store']

+exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store']

 # The name of the Pygments (syntax highlighting) style to use.

-pygments_style = 'default'

+pygments_style = 'sphinx'

 # If true, `todo` and `todoList` produce output, else they produce nothing.

 todo_include_todos = True

@@ -113,67 +90,24 @@ todo_include_todos = True

 # The theme to use for HTML and HTML Help pages.  See the documentation for

 # a list of builtin themes.

 #

-html_theme = 'sphinx_materialdesign_theme'

+html_theme = 'sphinx_rtd_theme'

 # Theme options are theme-specific and customize the look and feel of a theme

 # further.  For a list of options available for each theme, see the

 # documentation.

 #

-html_theme_options = {

-    # Specify a list of menu in Header.

-    # Tuples forms:

-    #  ('Name', 'external url or path of pages in the document', boolean, 'icon name')

-    #

-    # Third argument:

-    # True indicates an external link.

-    # False indicates path of pages in the document.

-    #

-    # Fourth argument:

-    # Specify the icon name.

-    # For details see link.

-    # https://material.io/icons/

-    'header_links': [

-        ('Home', 'index', False, 'home'),

-        ("GitHub", "https://github.com/SymbiFlow/prjtrellis", True, 'link')

-    ],

+# html_theme_options = {}

-    # Customize css colors.

-    # For details see link.

-    # https://getmdl.io/customize/index.html

-    #

-    # Values: amber, blue, brown, cyan deep_orange, deep_purple, green, grey, indigo, light_blue,

-    #         light_green, lime, orange, pink, purple, red, teal, yellow(Default: indigo)

-    'primary_color':

-    'deep_purple',

-    # Values: Same as primary_color. (Default: pink)

-    'accent_color':

-    'purple',

-

-    # Customize layout.

-    # For details see link.

-    # https://getmdl.io/components/index.html#layout-section

-    'fixed_drawer':

-    True,

-    'fixed_header':

-    True,

-    'header_waterfall':

-    True,

-    'header_scroll':

-    False,

-

-    # Render title in header.

-    # Values: True, False (Default: False)

-    'show_header_title':

-    False,

-    # Render title in drawer.

-    # Values: True, False (Default: True)

-    'show_drawer_title':

-    True,

-    # Render footer.

-    # Values: True, False (Default: True)

-    'show_footer':

-    True

-}

+# Enable github links when not on readthedocs

+on_rtd = os.environ.get('READTHEDOCS', None) == 'True'

+if not on_rtd:

+    html_context = {

+        "display_github": True,  # Integrate GitHub

+        "github_user": "symbiflow",  # Username

+        "github_repo": "prjtrellis",  # Repo name

+        "github_version": "master",  # Version

+        "conf_py_path": "/doc/",

+    }

 # 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,

@@ -250,17 +184,9 @@ intersphinx_mapping = {'https://docs.python.org/': None}

 def setup(app):

-    github_code_repo = 'https://github.com/SymbiFlow/prjtrellis/'

-    github_code_branch = 'blob/master/'

-

-    docs_root_dir = os.path.realpath(os.path.dirname(__file__))

-    code_root_dir = os.path.realpath(os.path.join(docs_root_dir, ".."))

-

-    MarkdownSymlinksDomain.init_domain(

-        github_code_repo, github_code_branch, docs_root_dir, code_root_dir)

-    MarkdownSymlinksDomain.find_links()

-    app.add_domain(MarkdownSymlinksDomain)

+    MarkdownCodeSymlinks.find_links()

     app.add_config_value(

         'recommonmark_config', {

-            'github_code_repo': github_code_repo,

+            'github_code_repo': 'https://github.com/SymbiFlow/prjtrellis',

         }, True)

+    app.add_transform(MarkdownCodeSymlinks)

diff --git a/docs/markdown_code_symlinks.py b/docs/markdown_code_symlinks.py

new file mode 100644

index 0000000..1955493

--- /dev/null

+++ b/docs/markdown_code_symlinks.py

@@ -0,0 +1,179 @@

+import logging

+import os

+

+from recommonmark import transform

+"""

+Allow linking of Markdown documentation from the source code tree into the Sphinx

+documentation tree.

+

+The Markdown documents will have links relative to the source code root, rather

+than the place they are now linked too - this code fixes these paths up.

+

+We also want links from two Markdown documents found in the Sphinx docs to

+work, so that is also fixed up.

+"""

+

+

+def path_contains(parent_path, child_path):

+    """Check a path contains another path.

+

+    >>> path_contains("a/b", "a/b")

+    True

+    >>> path_contains("a/b", "a/b/")

+    True

+    >>> path_contains("a/b", "a/b/c")

+    True

+    >>> path_contains("a/b", "c")

+    False

+    >>> path_contains("a/b", "c/b")

+    False

+    >>> path_contains("a/b", "c/../a/b/d")

+    True

+    >>> path_contains("../a/b", "../a/b/d")

+    True

+    >>> path_contains("../a/b", "../a/c")

+    False

+    >>> path_contains("a", "abc")

+    False

+    >>> path_contains("aa", "abc")

+    False

+    """

+    # Append a separator to the end of both paths to work around the fact that

+    # os.path.commonprefix does character by character comparisons rather than

+    # path segment by path segment.

+    parent_path = os.path.join(os.path.normpath(parent_path), '')

+    child_path = os.path.join(os.path.normpath(child_path), '')

+    common_path = os.path.commonprefix((parent_path, child_path))

+    return common_path == parent_path

+

+

+def relative(parent_dir, child_path):

+    """Get the relative between a path that contains another path."""

+    child_dir = os.path.dirname(child_path)

+    assert path_contains(parent_dir, child_dir), "{} not inside {}".format(

+        child_path, parent_dir)

+    return os.path.relpath(child_path, start=parent_dir)

+

+

+class MarkdownCodeSymlinks(transform.AutoStructify, object):

+    docs_root_dir = os.path.realpath(os.path.dirname(__file__))

+    code_root_dir = os.path.realpath(os.path.join(docs_root_dir, "..", ".."))

+

+    mapping = {

+        'docs2code': {},

+        'code2docs': {},

+    }

+

+    @classmethod

+    def relative_code(cls, url):

+        """Get a value relative to the code directory."""

+        return relative(cls.code_root_dir, url)

+

+    @classmethod

+    def relative_docs(cls, url):

+        """Get a value relative to the docs directory."""

+        return relative(cls.docs_root_dir, url)

+

+    @classmethod

+    def add_mapping(cls, docs_rel, code_rel):

+        assert docs_rel not in cls.mapping['docs2code'], """\

+Assertion error! Document already in mapping!

+    New Value: {}

+Current Value: {}

+""".format(docs_rel, cls.mapping['docs2code'][docs_rel])

+        assert code_rel not in cls.mapping['code2docs'], """\

+Assertion error! Document already in mapping!

+    New Value: {}

+Current Value: {}

+""".format(docs_rel, cls.mapping['code2docs'][code_rel])

+

+        cls.mapping['docs2code'][docs_rel] = code_rel

+        cls.mapping['code2docs'][code_rel] = docs_rel

+

+    @classmethod

+    def find_links(cls):

+        """Walk the docs dir and find links to docs in the code dir."""

+        for root, dirs, files in os.walk(cls.docs_root_dir):

+            for fname in files:

+                fpath = os.path.abspath(os.path.join(root, fname))

+

+                if not os.path.islink(fpath):

+                    continue

+

+                link_path = os.path.join(root, os.readlink(fpath))

+                # Is link outside the code directory?

+                if not path_contains(cls.code_root_dir, link_path):

+                    continue

+

+                # Is link internal to the docs directory?

+                if path_contains(cls.docs_root_dir, link_path):

+                    continue

+

+                docs_rel = cls.relative_docs(fpath)

+                code_rel = cls.relative_code(link_path)

+

+                cls.add_mapping(docs_rel, code_rel)

+        import pprint

+        pprint.pprint(cls.mapping)

+

+    @property

+    def url_resolver(self):

+        return self._url_resolver

+

+    @url_resolver.setter

+    def url_resolver(self, value):

+        print(self, value)

+

+    # Resolve a link from one markdown to another document.

+    def _url_resolver(self, ourl):

+        """Resolve a URL found in a markdown file."""

+        assert self.docs_root_dir == os.path.realpath(self.root_dir), """\

+Configuration error! Document Root != Current Root

+Document Root: {}

+ Current Root: {}

+""".format(self.docs_root_dir, self.root_dir)

+

+        src_path = os.path.abspath(self.document['source'])

+        src_dir = os.path.dirname(src_path)

+        dst_path = os.path.abspath(os.path.join(self.docs_root_dir, ourl))

+        dst_rsrc = os.path.relpath(dst_path, start=src_dir)

+

+        src_rdoc = self.relative_docs(src_path)

+

+        print

+        print("url_resolver")

+        print(src_path)

+        print(dst_path)

+        print(dst_rsrc)

+        print(src_rdoc)

+

+        # Is the source document a linked one?

+        if src_rdoc not in self.mapping['docs2code']:

+            # Don't do any rewriting on non-linked markdown.

+            url = ourl

+

+        # Is the destination also inside docs?

+        elif dst_rsrc not in self.mapping['code2docs']:

+            # Return a path to the GitHub repo.

+            url = "{}/blob/master/{}".format(

+                self.config['github_code_repo'], dst_rsrc)

+        else:

+            url = os.path.relpath(

+                os.path.join(

+                    self.docs_root_dir, self.mapping['code2docs'][dst_rsrc]),

+                start=src_dir)

+            base_url, ext = os.path.splitext(url)

+            assert ext in (".md",

+                           ".markdown"), ("Unknown extension {}".format(ext))

+            url = "{}.html".format(base_url)

+

+        print("---")

+        print(ourl)

+        print(url)

+        print

+        return url

+

+

+if __name__ == "__main__":

+    import doctest

+    doctest.testmod()

diff --git a/docs/requirements.txt b/docs/requirements.txt

index ec9e872..56c1f78 100644

--- a/docs/requirements.txt

+++ b/docs/requirements.txt

@@ -1,13 +1,8 @@

-sphinx_materialdesign_theme

-

 docutils

 sphinx

 sphinx-autobuild

 breathe

 recommonmark

-sphinx-markdown-tables

+sphinx_rtd_theme

 sphinxcontrib-napoleon

-

-# Markdown cross-reference solver library

-git+https://github.com/SymbiFlow/sphinxcontrib-markdown-symlinks

-- 

2.21.0