Introduction/tutorial doc improvements. (#512)

m-renaud · web-flow · commit 743b17d16dc9 · 2018-01-29T08:39:58.000-08:00
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]
diff --git a/.gitmodules b/.gitmodules
@@ -0,0 +1,3 @@
+[submodule "docs/_extensions/haddock-autolink"]
+	path = docs/_extensions/haddock-autolink
+	url = https://github.com/m-renaud/haddock-autolink
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -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`.
+dependencies, `git submodule update --init`, and then `cd docs/ && make html`.
diff --git a/docs/_extensions/HaddockAutolinker.py b/docs/_extensions/HaddockAutolinker.py
diff --git a/docs/_extensions/haddock-autolink b/docs/_extensions/haddock-autolink
@@ -0,0 +1 @@
+Subproject commit 51c39abba4ceacd5a171603e43453a6cfe7e2ac6
diff --git a/docs/_extensions/haddock-autolink.py b/docs/_extensions/haddock-autolink.py
diff --git a/docs/_extensions/hs-theme.py b/docs/_extensions/hs-theme.py
@@ -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
@@ -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
diff --git a/docs/_static/images/haskell-logo-green.svg b/docs/_static/images/haskell-logo-green.svg
@@ -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>
diff --git a/docs/_templates/layout.html b/docs/_templates/layout.html
@@ -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 %}
diff --git a/docs/conf.py b/docs/conf.py
@@ -14,10 +14,12 @@
 
 # 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 @@
 
 # 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 @@
 # 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/",
diff --git a/docs/index.rst b/docs/index.rst
@@ -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`
diff --git a/docs/intro.rst b/docs/intro.rst
@@ -1,5 +1,5 @@
-Introduction
-============
+``containers`` Introduction
+===========================
 
 The ``containers`` package provides implementations of various immutable data
 structures.
diff --git a/docs/sequence.rst b/docs/sequence.rst
@@ -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``.
 

Original file line number	Diff line number	Diff line change
`@@ -0,0 +1,3 @@`
	`1`	`+[submodule "docs/_extensions/haddock-autolink"]`
	`2`	`+ path = docs/_extensions/haddock-autolink`
	`3`	`+ url = https://github.com/m-renaud/haddock-autolink`
Original file line number	Diff line number	Diff line change
`@@ -0,0 +1,2 @@`
	`1`	`+def setup(app):`
	`2`	`+ app.add_stylesheet('css/hs-theme.css')`