documentation update w/ page ToCs

CountESS-Project · Nov 28, 2023 · 6bd5a51 · 6bd5a51
1 parent 72d9bf8
commit 6bd5a51
Show file tree

Hide file tree

Showing 15 changed files with 401 additions and 8 deletions.
diff --git a/.gitignore b/.gitignore
@@ -9,3 +9,8 @@ build/
 .direnv/
 result*
 junk/
+docs/_site/
+docs/.jekyll-metadata
+*.backup
+coverage.json
+.coverage
diff --git a/docs/_config.yml b/docs/_config.yml
@@ -1,3 +1,5 @@
 title: "CountESS: Documentation"
+description: "CountESS: Documentation"
+email: nick@zoic.org
 baseurl: /
 url: https://countess-project.github.io
diff --git a/docs/_layouts/default.html b/docs/_layouts/default.html
@@ -1,14 +1,22 @@
+<!DOCTYPE html>
 <html>
   <head>
      <title>{{ page.title }}</title>
-     <link rel="stylesheet" href="{{ site.baseurl }}/css/vanilla.css">
-     <link rel="stylesheet" href="{{ site.baseurl }}/css/custom.css">
+     <link rel="stylesheet" href="{{ site.url }}{{ site.baseurl }}/css/vanilla.css">
+     <link rel="stylesheet" href="{{ site.url }}{{ site.baseurl }}/css/custom.css">
+     <script src="{{ site.url }}{{ site.baseurl }}/js/toc.js"></script>
   </head>
   <body>
-    {% if page.url != "/" %}
-      <div class="navbar"><a href="{{ site.baseurl }}/">CountESS Documentation</a></div>
-      {% if page.parent %}/ <a href="../">{{ page.parent }}</a>{% endif %}
-    {% endif %}
+    <div id="toc" class="sidebar">
+      <p>
+        {% if page.url != "/" %}
+          <a href="{{ site.url }}{{ site.baseurl }}">CountESS Documentation</a></p>
+          {% if page.parent %}/ <a href="../">{{ page.parent }}</a>{% endif %}
+        {% endif %} 
+      </p>
+    </div>
+    <div class="content" id="content">
     {{ content }}
+    </div>
   </body>
 </html>
diff --git a/docs/contributing/index.md b/docs/contributing/index.md
@@ -1,3 +1,7 @@
+---
+layout: default
+---
+
 # Contributing to CountESS
 
 CountESS is an open source project and we welcome contributions.

diff --git a/docs/css/custom.css b/docs/css/custom.css
@@ -1,5 +1,9 @@
 /* little overrides to vanilla.css */
 
+body {
+	max-width: 120ch;
+}
+
 div.navbar {
     display: block;
     border-bottom: 2px solid var(--tertiary-color);
@@ -17,3 +21,27 @@ table code {
 table th code {
     font-weight: bold;
 }
+
+@media (min-width: 48em) {
+    .content {
+	 max-width: 38rem;
+	 margin-left: 18rem;
+	 margin-right: 2rem;
+    }
+    .sidebar {
+	 max-width: 16rem;
+	 position: fixed;
+    }
+}
+
+@media (min-width: 64em) {
+  .content {
+    margin-left: 22rem;
+    margin-right: 2rem;
+  }
+  .sidebar {
+	max-width: 20rem;
+	position: fixed;
+}
+}
+
diff --git a/docs/documentation/index.md b/docs/documentation/index.md
@@ -0,0 +1,45 @@
+---
+layout: default
+---
+
+# CountESS Documentation
+
+This site is generated
+[from markdown source](https://github.com/CountESS-Project/CountESS/tree/main/docs)
+by Github Pages.
+
+To contribute to documentation, [raise a pull request](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/creating-a-pull-request).
+
+## Building Documentation Locally
+
+Documentation is built automatically by Github Pages, but you can build it locally 
+as well using 'jekyll' to check it is all working properly.
+
+### Installing Jekyll
+
+See:
+
+* [About Github Pages & Jekyll](https://docs.github.com/en/pages/setting-up-a-github-pages-site-with-jekyll/about-github-pages-and-jekyll)
+* [Jekyll Install Instructions](https://jekyllrb.com/docs/installation/)
+
+Under Ubuntu, `apt install jekyll` should be enough.
+
+### Running Jekyll
+
+Jekyll will compile the site and write it into the `_site` subdirectory. 
+Please do not add this directory to the repository.
+
+To build the documentation once, run:
+
+        jekyll build
+
+or to run a local HTTP server run:
+
+        jekyll serve --incremental
+
+## Themes, CSS, etc.
+
+The theming is minimal, using [vanilla.css](https://vanillacss.com/) and
+very little else.  Page tables of contents aren't really necessary for 
+navigation but for convenience they are generated on page load by
+[a very small piece of javascript](https://github.com/CountESS-Project/CountESS/tree/main/docs/js/toc.js).
diff --git a/docs/included-plugins/index.md b/docs/included-plugins/index.md
@@ -1,3 +1,7 @@
+---
+layout: default
+---
+
 # Included Plugins
 
 CountESS is designed to be easy to write plugins for, but plugins are included for common file formats and simple data transformations.

diff --git a/docs/index.md b/docs/index.md
@@ -1,10 +1,14 @@
+---
+title: CountESS Documentation
+layout: default
+---
+
 # CountESS Documentation
 
 This is CountESS, a modular, Python 3 reimplementation of Enrich2.
 
 [Source code is available](https://github.com/CountESS-Project/CountESS)
-and contributions are welcomed.  [This documentation is generated](https://github.com/CountESS-Project/CountESS/tree/main/docs)
-from the `/docs/` directory and documentation fixes are also welcomed!
+and contributions to code and documentation are welcomed.
 
 CountESS is copyright (C) 2022- CountESS Developers, and is made available
 under a [BSD 3-clause license](license/).
@@ -18,6 +22,7 @@ under a [BSD 3-clause license](license/).
 * [Writing Plugins](writing-plugins/)
 * [Configuration File Format](config-file-format/)
 * [Contributing to CountESS](contributing/)
+* [CountESS Dcoumentation](documentation/)
 
 ## Presentations
 

diff --git a/docs/installing-countess/index.md b/docs/installing-countess/index.md
@@ -1,3 +1,7 @@
+---
+layout: default
+---
+
 # Installing CountESS
 
 ## ... using pip
@@ -64,6 +68,12 @@ we use [homebrew](https://brew.sh/) to install more recent versions.
 
    The CountESS binaries `countess_gui` and `countess_cli` should now be available from your shell.
 
+4. Installing with HDF5 support
+
+        brew install hdf5
+        pip3.10 install countess[hdf5]
+
+
 # NEXT
 
 Now CountESS is installed, see [Running CountESS](../running-countess/)
diff --git a/docs/js/toc.js b/docs/js/toc.js
@@ -0,0 +1,88 @@
+// from https://stackoverflow.com/a/67552284
+// by CMSG https://stackoverflow.com/users/8469099/cmsg
+// slightly modified by Nick to keep heading id if id already exists
+
+// Let the DOM content load before running the script.
+window.addEventListener('DOMContentLoaded', function (event) {
+    //Get all headings only from the actual contents.
+    var contentContainer = document.getElementById('content'); // Add this div to the html
+
+    var headings = contentContainer.querySelectorAll('h1,h2,h3,h4,h5'); // You can do as many or as few headings as you need.
+
+    // NICK: Don't bother running if no or only one heading
+
+    if (headings.length < 2) return;
+
+    var tocContainer = document.getElementById('toc'); // Add this div to the HTML
+    // create ul element and set the attributes.
+    var ul = document.createElement('ul');
+
+    ul.setAttribute('id', 'tocList');
+    ul.setAttribute('class', 'sidenav')
+
+    // Loop through the headings NodeList
+    for (i = 0; i <= headings.length - 1; i++) {
+
+	// NICK: keep id if there already is one.
+
+        var id = headings[i].id || headings[i].innerHTML.toLowerCase().replace(/ /g, "-"); // Set the ID to the header text, all lower case with hyphens instead of spaces.
+        var level = headings[i].localName.replace("h", ""); // Getting the header a level for hierarchy
+        var title = headings[i].innerHTML; // Set the title to the text of the header
+
+        headings[i].setAttribute("id", id)  // Set header ID to its text in lower case text with hyphens instead of spaces.
+
+        var li = document.createElement('li');     // create li element.
+        li.setAttribute('class', 'sidenav__item') // Assign a class to the li
+        var a = document.createElement('a'); // Create a link
+        a.setAttribute("href", "#" + id) // Set the href to the heading ID
+        a.innerHTML = title; // Set the link text to the heading text
+
+        // Create the hierarchy
+
+        if(level == 1) {
+            li.appendChild(a); // Append the link to the list item
+            ul.appendChild(li);     // append li to ul.
+        } else if (level == 2) {
+            child = document.createElement('ul'); // Create a sub-list
+            child.setAttribute('class', 'sidenav__sublist')
+            li.appendChild(a); 
+            child.appendChild(li);
+            ul.appendChild(child);
+        } else if (level == 3) {
+            grandchild = document.createElement('ul');
+            grandchild.setAttribute('class', 'sidenav__sublist')
+            li.appendChild(a);
+            grandchild.appendChild(li);
+            child.appendChild(grandchild);
+        } else if (level == 4) {
+            great_grandchild = document.createElement('ul');
+            great_grandchild.setAttribute('class', 'sidenav__sublist');
+            li.append(a);
+            great_grandchild.appendChild(li);
+            grandchild.appendChild(great_grandchild);
+        } else if (level == 5) {
+            great_great_grandchild = document.createElement('ul');
+            great_great_grandchild.setAttribute('class', 'sidenav__sublist');
+            li.append(a);
+            great_great_grandchild.appendChild(li);
+            great_grandchild.appendChild(great_great_grandchild);
+        }
+    }
+
+    tocContainer.appendChild(ul);       // add list to the container
+
+    // Add a class to the first list item to allow for toggling active state.
+    var links = tocContainer.getElementsByClassName("sidenav__item");
+
+    links[0].classList.add('current');
+
+    // Loop through the links and add the active class to the current/clicked link
+    for (var i = 0; i < links.length; i++) {
+        links[i].addEventListener("click", function() {
+            var current = document.getElementsByClassName("current");
+            current[0].className = current[0].className.replace(" current", "");
+            this.className += " current";
+        });
+    }
+});
+
diff --git a/docs/license/index.md b/docs/license/index.md
@@ -1,3 +1,7 @@
+---
+layout: default
+---
+
 # Licensing
 
 CountESS, including this documentation, is licensed under the

diff --git a/docs/other-plugins/index.md b/docs/other-plugins/index.md
@@ -1,3 +1,7 @@
+---
+layout: default
+---
+
 # Other Plugins
 
 [CountESS comes with many plugins included](../included-plugins/) and anyone can