Introduction/tutorial doc improvements. (#512)
authorMatt Renaud <matt@m-renaud.com>
Mon, 29 Jan 2018 16:39:58 +0000 (08:39 -0800)
committerGitHub <noreply@github.com>
Mon, 29 Jan 2018 16:39:58 +0000 (08:39 -0800)
Changes:
--------

- Update titles so that package name is visible in browser tabs
- Fix typo in sequence docs
- Use https://github.com/m-renaud/haddock-autolink
- Update theme (dark grey with green) for desktop and mobile

Why use a submodule?
--------------------

Improvements to the autolinker don't need to take place in the containers repo. Also, if other projects end up using it the code doesn't get out of sync (not everyone needs to copy/paste the Sphinx extension).

If you're not modifying the docs you don't need to pull down all the Python code. If you do want to build the container docs locally you need to pull down the submodule code (see the CONTRIBUTING.md file for exact commands to run).

Read the docs natively supports submodules so this has no visible effect on the docs.

[ci skip]

14 files changed:
.gitmodules [new file with mode: 0644]
CONTRIBUTING.md
docs/_extensions/HaddockAutolinker.py [deleted file]
docs/_extensions/haddock-autolink [new submodule]
docs/_extensions/haddock-autolink.py [deleted file]
docs/_extensions/hs-theme.py [new file with mode: 0644]
docs/_static/css/hs-theme.css [new file with mode: 0644]
docs/_static/images/favicon-green-16x16.png [new file with mode: 0644]
docs/_static/images/haskell-logo-green.svg [new file with mode: 0644]
docs/_templates/layout.html
docs/conf.py
docs/index.rst
docs/intro.rst
docs/sequence.rst

diff --git a/.gitmodules b/.gitmodules
new file mode 100644 (file)
index 0000000..0933b78
--- /dev/null
@@ -0,0 +1,3 @@
+[submodule "docs/_extensions/haddock-autolink"]
+       path = docs/_extensions/haddock-autolink
+       url = https://github.com/m-renaud/haddock-autolink
index 16d74d9..b23942c 100644 (file)
@@ -81,4 +81,4 @@ haddock` or `stack haddock`.
 The external docs are served by ReadTheDocs at
 https://haskell-containers.readthedocs.io and live in the `docs/` directory. To
 build the docs locally run `pip install sphinx sphinx-autobuild` to install the
-dependencies and then `cd docs/ && make html`.
\ No newline at end of file
+dependencies, `git submodule update --init`, and then `cd docs/ && make html`.
diff --git a/docs/_extensions/HaddockAutolinker.py b/docs/_extensions/HaddockAutolinker.py
deleted file mode 100644 (file)
index 63335e3..0000000
+++ /dev/null
@@ -1,233 +0,0 @@
-from docutils import nodes
-import itertools
-import string
-
-### Utility functions.
-
-def get_project(inliner):
-    """
-    Returns the project name associated with the file being processed.
-    """
-    return inliner.document.settings.env.app.config.project
-
-
-def convert_special_chars_to_ascii(func_name):
-    """
-    If func_name is an operator, convert it to its ascii representation.
-
-    This is how Haddock generates links for operators.
-
-    '!?' => '-33--63-'
-    """
-    if func_name == None:
-        return None
-
-    escaped_func_name = [ c if c not in string.punctuation else '-' + str(ord(c)) + '-'
-                          for c in func_name ]
-
-    return ''.join(escaped_func_name)
-
-
-def parse_haddock_ref_text(text):
-    """
-    Parses text of the form pkg-name/Module.Path#ident into the tuple
-    (package, module, ident).
-
-    The module and function name are optional, if they are omitted then 'None'
-    will be returned in the corresponding tuple element.
-
-    Example inputs:
-      Explicit package references:
-      'pkg' => ('package_name', None, None)
-      'pkg/Module.Name' => ('pkg', 'Module.Name', None)
-      'pkg/Module.Name#ident' => ('pkg', 'Module.Name', 'ident')
-
-      Implicit package references:
-      '/Module.Name' => (None, 'Module.Name', None)
-      '/Module.Name#ident' => (None, 'Module.Name', 'ident')
-
-    TODO(m-renaud): Clean this up, there's probably a python parsing library.
-    """
-
-    # If there's no '/' then this is a reference to a package.
-    # A module or identifier reference is invalid here.
-    if '/' not in text:
-        if '#' in text:
-            print_error('Invalid haddock reference: ' + text)
-            raise Exception('Invalid haddock reference, see error above.')
-            return (None, None, None)
-        else:
-            return (text, None, None)
-
-    # Leading '/' means local package reference.
-    # Calling code responsible for determining what "local" means.
-    if 0 == text.find('/'):
-        text = text[1:]
-        if '#' in text:
-            module,ident = text.split('#')
-            return (None, module, ident)
-        else:
-            return (None, text, None)
-
-    # Otherwise, explicit reference.
-    pkg_name,rest = text.split('/')
-
-    ident = None
-    module = None
-    if '#' in rest:
-        module,ident = rest.split('#')
-    else:
-        module = rest
-
-    return (pkg_name, module, ident)
-
-
-
-### Link generation functions.
-
-def pkg_root_ref(haddock_host, haddock_root, pkg):
-    """
-    Returns the URI for the root of pkg's Haddocks.
-
-    Note: Hackage uses a different URI scheme than stackage and local.
-
-    URI enclosed in {} corresponds to 'haddock_root'.
-
-    Hackage: {hackage.haskell.org/package/}<pkg_name>
-    Stackage: {www.stackage.org/haddock/<resolver>/}<pkg_name>/index.html
-    Local: {file:///path/to/html/}<pkg_name>/index.html
-    """
-
-    if haddock_host == 'hackage':
-        return haddock_root + pkg
-
-    if haddock_host == 'stackage':
-        return haddock_root + pkg + '/index.html'
-
-    if haddock_host == 'local':
-        return haddock_root + pkg + '/index.html'
-
-
-def module_ref(haddock_host, haddock_root, pkg, module, func_name):
-    """
-    Returns the URI referring to pkg/module#func_name.
-
-    Note: Hackage uses a different URI scheme than stackage and local.
-
-    URI enclosed in {} corresponds to 'haddock_root'.
-
-    Hackage: {hackage.haskell.org/package/}<pkg_name>/docs/<module>.html#v:<func_name>
-    Stackage: {www.stackage.org/haddock/<resolver>/}<pkg_name>/<module>.html#t:<func_name>
-    Local: {file:///path/to/html/}<pkg_name>/<module>.html#t:<func_name>
-    """
-
-    if module != None:
-        module = module.replace('.', '-')
-
-    if haddock_host == 'hackage':
-        ref = haddock_root + pkg + '/docs/' + module + '.html'
-
-    if haddock_host == 'stackage':
-        ref = haddock_root + pkg + '/' + module + '.html'
-
-    if haddock_host == 'local':
-        ref = haddock_root + pkg + '/' + module + '.html'
-
-    # If a function name was provided, link to it.
-    if func_name != None:
-        # Select the correct anchor, types use #t, functions use #v.
-        if func_name[0].isupper():
-            anchor_type = '#t:'
-        else:
-            anchor_type = '#v:'
-        ref = ref + anchor_type + func_name
-
-    return ref
-
-
-def haddock_ref(haddock_host, haddock_root, pkg, module, func_name):
-    """
-    Return a reference link to Haddocks for pkg/module#func_name.
-    """
-
-    if module == None and func_name == None:
-        return pkg_root_ref(haddock_host, haddock_root, pkg)
-    else:
-        func_name = convert_special_chars_to_ascii(func_name)
-        return module_ref(haddock_host, haddock_root, pkg, module, func_name)
-
-
-
-#############################################
-# -- Custom roles for linking to Hackage docs
-#############################################
-
-# Support building docs with link to hackage, stackage, or locally build haddocks.
-# Valid options:
-#   hackage - link to hackage.haskell.org
-#   stackage - link to www.stackage.org (must also pass STACKAGE_RESOLVER)
-#   local - any path to local docs (must also set HADDOCK_DIR)
-#
-# Note: Defaults to hackage if none specified.
-#
-# Note: We need to do some custom URL rewriting for stackage because it uses a different
-# format from what the haddock tool builds
-#
-# TODO(m-renaud): Improve this and publish as sphinx extension.
-
-### URI scheme examples for Hackage, Stackage, and local docs.
-## Packages
-# Hackage: hackage.haskell.org/package/containers
-# Stackage: www.stackage.org/haddock/lts-10.0/containers/index.html
-# Local: file:///local/path/html/containers/index.html
-
-## Module (and function) references
-# Hackage: hackage.haskell.org/package/containers/docs/Data.Set.html#v:empty
-# Stackage: www.stackage.org/haddock/lts-10.0/containers/Data.Set.html#t:empty
-# Local: file:///path/to/html/containers/Data.Set.html#t:empty
-
-class HaddockAutolinker:
-
-    def __init__(self, app, haddock_host, haddock_root):
-        self.haddock_host = haddock_host
-        self.haddock_root = haddock_root
-
-
-    def haddock_role(self, display_name_only=False):
-        def haddock_role_impl(name, rawtext, text, lineno, inliner, options={}, content=[]):
-            """
-            Role handler for :haddock:.
-            """
-
-            (pkg, module, ident) = parse_haddock_ref_text(text)
-
-            # If the pkg isn't set then this is a local reference to a module
-            # function in the current package.
-            if pkg == None:
-                pkg = get_project(inliner)
-            ref = haddock_ref(self.haddock_host, self.haddock_root, pkg, module, ident)
-
-            if ref == None:
-                FAIL = '\033[91m'
-                ENDC = '\033[0m'
-                print FAIL
-                print 'ERROR: invalid argument to :' + name + ':'
-                print 'Markup: ' + str(rawtext)
-                print 'Line: ' + str(lineno)
-                print ENDC
-                raise Exception('Invalid Haddock link, see ERROR above.')
-
-            if module == None:
-                link_text = pkg
-            else:
-                if ident == None:
-                    link_text = module
-                else:
-                    if display_name_only:
-                        link_text = ident
-                    else:
-                        link_text = module + '#' + ident
-
-            node = nodes.reference(rawtext, link_text, refuri=ref, **options)
-            return [node], []
-        return haddock_role_impl
diff --git a/docs/_extensions/haddock-autolink b/docs/_extensions/haddock-autolink
new file mode 160000 (submodule)
index 0000000..51c39ab
--- /dev/null
@@ -0,0 +1 @@
+Subproject commit 51c39abba4ceacd5a171603e43453a6cfe7e2ac6
diff --git a/docs/_extensions/haddock-autolink.py b/docs/_extensions/haddock-autolink.py
deleted file mode 100644 (file)
index 1a5d710..0000000
+++ /dev/null
@@ -1,50 +0,0 @@
-from docutils import nodes
-from HaddockAutolinker import (HaddockAutolinker, haddock_ref)
-import os
-
-
-def setup(app):
-    haddock_host = os.getenv('HADDOCK_HOST', 'hackage')
-
-    # Hackage hosting
-    if haddock_host == 'hackage':
-        haddock_root = 'https://hackage.haskell.org/package/'
-
-    # Stackage hosting
-    elif haddock_host == 'stackage':
-        stackage_resolver = os.getenv('STACKAGE_RESOLVER', None)
-        if stackage_resolver != None:
-            haddock_root = 'https://www.stackage.org/haddock/' + stackage_resolver + '/'
-        else:
-            raise Exception("Must specify STACKAGE_RESOLVER when setting HADDOCK_HOST=stackage")
-
-    # Local hosting
-    elif haddock_host == 'local':
-        haddock_dir = os.getenv('HADDOCK_DIR', None)
-        if haddock_dir != None:
-            haddock_root = haddock_dir
-        else:
-            raise Exception("Must specify HADDOCK_DIR when setting HADDOCK_HOST=local")
-
-    else:
-        raise Exception("HADDOCK_HOST not recognized, valid options: hackage, stackage, local")
-
-    # These custom roles allow you to easily link to Haddock documentation using
-    # :role_name:`function_name`.
-    #
-    # For example:
-    #   :set:`insert` will create a link to
-    #   https://hackage.haskell.org/package/containers-0.5.10.2/docs/Data-Set.html#v:insert
-    autolinker = HaddockAutolinker(app, haddock_host, haddock_root)
-
-    app.add_role('haddock', autolinker.haddock_role())
-    app.add_role('haddock_short', autolinker.haddock_role(True))
-
-
-    print '\nHaddock host information'
-    print '  haddoc_host: ' + haddock_host
-    print '  haddock_root: ' + haddock_root
-    print
-    print '  Links to docs will be of the form: ' + \
-        haddock_ref(haddock_host, haddock_root, 'pkg-name', 'Module-Name', 'funcName')
-
diff --git a/docs/_extensions/hs-theme.py b/docs/_extensions/hs-theme.py
new file mode 100644 (file)
index 0000000..8201ff8
--- /dev/null
@@ -0,0 +1,2 @@
+def setup(app):
+    app.add_stylesheet('css/hs-theme.css')
diff --git a/docs/_static/css/hs-theme.css b/docs/_static/css/hs-theme.css
new file mode 100644 (file)
index 0000000..98088de
--- /dev/null
@@ -0,0 +1,11 @@
+.wy-side-nav-search {
+    background-color: #222 !important;
+}
+
+.wy-nav-top {
+    background-color: #333 !important;
+}
+
+.wy-nav-top i {
+    color: #282 !important;
+}
diff --git a/docs/_static/images/favicon-green-16x16.png b/docs/_static/images/favicon-green-16x16.png
new file mode 100644 (file)
index 0000000..7c691aa
Binary files /dev/null and b/docs/_static/images/favicon-green-16x16.png differ
diff --git a/docs/_static/images/haskell-logo-green.svg b/docs/_static/images/haskell-logo-green.svg
new file mode 100644 (file)
index 0000000..906af03
--- /dev/null
@@ -0,0 +1,17 @@
+<svg width="520" height="400" xmlns="http://www.w3.org/2000/svg" preserveAspectRatio="xMidYMid meet">
+ <metadata>Created by potrace 1.15, written by Peter Selinger 2001-2017</metadata>
+
+ <g>
+  <title>background</title>
+  <rect fill="none" id="canvas_background" height="402" width="522" y="-1" x="-1"/>
+ </g>
+ <g>
+  <title>Layer 1</title>
+  <g id="svg_1" transform="translate(0,512) scale(0.10000000149011612,-0.10000000149011612) ">
+   <path fill="#252" id="svg_2" d="m10,4896.689087c0,-5 269,-412 599,-906l598,-898l-598,-897c-330,-493 -599,-901 -599,-907c0,-7 158,-9 458,-7l459,2l602,904l603,904l-604,905l-603,906l-457,1c-252,0 -458,-3 -458,-7z"/>
+   <path fill="#282" id="svg_3" d="m1210,4898.689087c0,-4 270,-411 600,-905l600,-900l-600,-900c-330,-495 -600,-902 -600,-905c0,-3 207,-5 460,-5l459,0l367,550c201,303 369,552 374,555c4,2 173,-245 376,-550l369,-554l458,-1c251,0 457,3 457,7c0,5 -541,819 -1202,1810l-1201,1803l-459,0c-252,0 -458,-2 -458,-5z"/>
+   <path fill="#252" id="svg_4" d="m3127,3822.689087c11,-16 103,-155 204,-309l184,-279l808,0l807,-1l0,310l0,310l-1011,0l-1011,0l19,-31z"/>
+   <path fill="#252" id="svg_5" d="m3722,2938.689087c2,-8 91,-147 198,-309l195,-295l508,0l507,-1l0,310l0,310l-706,0c-621,0 -705,-2 -702,-15z"/>
+  </g>
+ </g>
+</svg>
index 0691552..57f1b91 100644 (file)
@@ -2,5 +2,6 @@
 
 {%- block extrahead %}
   <meta name="google-site-verification" content="boeOM2WSruQOlY6qXpjFvi9gZglAGs-bgkiDvcsvf4Y" />
-  <link rel="shortcut icon" type="image/png" href="_static/images/favicon-16x16.png"/>
+  <link rel="shortcut icon" type="image/png" href="_static/images/favicon-green-16x16.png"/>
+  <meta name="theme-color" content="#222" />
 {% endblock %}
index 53001fa..a9d9eb1 100644 (file)
@@ -14,10 +14,12 @@ import sys
 
 # Add the _extenions dir to the search path.
 sys.path.insert(0, os.path.abspath('.') + '/_extensions')
+sys.path.insert(0, os.path.abspath('.') + '/_extensions/haddock-autolink')
 
 extensions = ['sphinx.ext.intersphinx',
               'sphinx.ext.ifconfig',
-              'haddock-autolink']
+              'haddock-autolink',
+              'hs-theme']
 
 templates_path = ['_templates']
 
@@ -27,7 +29,7 @@ master_doc = 'index'
 
 # General information about the project.
 project = u'containers'
-copyright = u'2017, Matt Renaud'
+copyright = u'2018, Matt Renaud'
 author = u'Matt Renaud'
 
 # The short X.Y version.
@@ -73,7 +75,7 @@ if not on_rtd:  # only import and set the theme if we're building docs locally
 # 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_logo = '_static/images/haskell-logo-black.svg'
+html_logo = '_static/images/haskell-logo-green.svg'
 html_static_path = ['_static']
 html_context = {
     'source_url_prefix': "https://github.com/haskell/containers/tree/master/docs/",
index 7b48f60..cad1868 100644 (file)
@@ -1,5 +1,5 @@
-Haskell ``containers`` introduction and tutorial
-================================================
+``containers`` - Introduction and Tutorial
+==========================================
 
 This site contains an introduction and overview of the main features of the
 ``containers`` package. For full API documentation see the :haddock:`containers`
index 32ae191..ea4750a 100644 (file)
@@ -1,5 +1,5 @@
-Introduction
-============
+``containers`` Introduction
+===========================
 
 The ``containers`` package provides implementations of various immutable data
 structures.
index 7b32455..412f8b7 100644 (file)
@@ -188,7 +188,7 @@ Adding to an existing sequence
     (><) :: Seq a -> Seq a -> Seq a
     l >< r = ...
 
-- ``x <| xs`` places the element ``x`` at the beginning of the sequence ``xs``..
+- ``x <| xs`` places the element ``x`` at the beginning of the sequence ``xs``.
 
 - ``xs |> x`` places the element ``x`` at the end of the sequence ``xs``.