docs: Upgrade documentation site (#1365)

doc/_sphinx/conf.py

@@ -3,14 +3,14 @@
 # This file only contains a selection of the most common options. For a full
 # list see the documentation:
 # https://www.sphinx-doc.org/en/master/usage/configuration.html
-
+import docutils
+import os
 
 # -- Project information -----------------------------------------------------
 
 project = 'Flame'
 copyright = '2021, Blue Fire Team'
 author = 'Blue Fire Team'
-
 root_doc = "index"
 
 
@@ -47,17 +47,8 @@
 # -- Options for HTML output -------------------------------------------------
 
 # The theme to use for HTML and HTML Help pages.
-html_theme = "sphinx_book_theme"
-
-# See https://sphinx-book-theme.readthedocs.io/en/latest/customize/index.html
-html_theme_options = {
- "logo_only": True,
- "path_to_docs": "doc",
- "repository_branch": "main",
- "repository_url": "https://github.com/flame-engine/flame",
- "use_edit_page_button": True,
- "use_repository_button": True,
-}
+html_theme = "flames"
+html_theme_options = {}
 html_title = "Flame"
 html_logo = "images/logo_flame.png"
 html_favicon = "images/favicon.ico"
@@ -68,6 +59,66 @@
 # 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_static_path = ['images', 'styles', 'scripts']
-html_css_files = ['custom.css']
+html_static_path = ['images', 'scripts', 'theme']
 html_js_files = ['versions.js']
+
+# -- Custom setup ------------------------------------------------------------
+class TitleCollector(docutils.nodes.SparseNodeVisitor):
+ def __init__(self, document):
+ self.level = 0
+ self.titles = []
+ super().__init__(document)
+
+ def visit_section(self, node):
+ title_class = docutils.nodes.title
+ self.level += 1
+ if node.children and isinstance(node.children[0], title_class):
+ title = node.children[0].astext()
+ node_id = node.get("ids")[0]
+ self.titles.append([title, node_id, self.level])
+
+ def depart_section(self, node):
+ self.level -= 1
+
+
+
+def get_local_toc(document):
+ if not document:
+ return ""
+ visitor = TitleCollector(document)
+ document.walkabout(visitor)
+ titles = visitor.titles
+ if not titles:
+ return ""
+
+ levels = sorted(set(item[2] for item in titles))
+ if levels.index(titles[0][2]) != 0:
+ return document.reporter.error(
+ "First title on the page is not <h1/>")
+ del titles[0] # remove the <h1> title
+
+ h1_seen = False
+ ul_level = 0
+ html_text = "<div id='toc-local' class='list-group'>\n"
+ html_text += " <div class='header'><i class='fa fa-list'></i> Contents</div>\n"
+ for title, node_id, level in titles:
+ if level <= 1:
+ return document.reporter.error("More than one <h1> title on the page")
+ html_text += f" <a href='#{node_id}' class='list-group-item level-{level-1}'>{title}</a>\n"
+ html_text += "</div>\n"
+ return html_text
+
+
+
+# Emitted when the HTML builder has created a context dictionary to render
+# a template with – this can be used to add custom elements to the context.
+def on_html_page_context(app, pagename, templatename, context, doctree):
+ context["get_local_toc"] = lambda: get_local_toc(doctree)
+
+
+def setup(app):
+ this_dir = os.path.dirname(__file__)
+ theme_dir = os.path.abspath(os.path.join(this_dir, 'theme'))
+ app.add_css_file('flames.css')
+ app.add_html_theme('flames', theme_dir)
+ app.connect("html-page-context", on_html_page_context)

doc/_sphinx/requirements.txt

@@ -2,5 +2,4 @@ linkify-it-py>=1.0
 myst-parser>=0.15.2
 pygments>=2.10
 sphinx>=4.2
-sphinx-book-theme>=0.1.4
 sphinxcontrib-mermaid>=0.7.1

doc/_sphinx/scripts/versions.js

@@ -10,7 +10,7 @@ function getCurrentDocVersion() {
  return parts[1];
  }
  }
- return '--';
+ return 'local';
 }
 
 // Given a list of versions (as plain strings), convert them into HTML <A/>
@@ -24,23 +24,33 @@ function convertVersionsToHtmlLinks(versionsList, currentVersion) {
  if (version === currentVersion) {
  classes += ' selected';
  }
- out += `<a href="/${version}/"><button class="${classes}">${version}</button></a>`;
+ out += `<a href="/${version}/">
+ <button class="${classes}">
+ <i class="fa fa-code-branch"></i> ${version}
+ </button>
+ </a>`;
  }
  return out;
 }
 
 function buildVersionsMenu(data) {
  const currentVersion = getCurrentDocVersion();
  const versionButtons = convertVersionsToHtmlLinks(data.split('\n'), currentVersion);
- $('div.topbar-main').append(`
- <div class="dropdown-buttons-trigger" id="versions-menu">
- <button class="btn btn-secondary topbarbtn">
- <span class="tag">version:</span>
+ $('div.versions-placeholder').append(`
+ <div id="versions-menu" tabindex="-1">
+ <div class="btn">
+ <i class="fa fa-code-branch"></i>
  <span class="version-id">${currentVersion}</span>
- </button>
- <div class="dropdown-buttons">${versionButtons}</div>
+ </div>
+ <div class="dropdown-buttons">
+ <div class="header">View documentation for version:</div>
+ ${versionButtons}
+ </div>
  </div>
  `);
+ $("#versions-menu").on("click blur", function() {
+ $(this).toggleClass("active");
+ });
 }
 
 // Start loading the versions list as soon as possible, don't wait for DOM
@@ -51,5 +61,9 @@ const versionsRequest = $.get(
 // Now wait for DOM to finish loading
 $(function() {
  // Lastly, wait for versions to finish loading too.
- versionsRequest.then(buildVersionsMenu);
+ versionsRequest.then(buildVersionsMenu)
+ .fail(function() {
+ console.log("Failed to load versions.txt, using default version list");
+ buildVersionsMenu("local\nmain\n1.0.0\n");
+ });
 });