Merge pull request #189 from supertokens/fix-multiple-h1-issue

docs: fixes issue of multiple h1 present in python docs

Author: rishabhpoddar

CHANGELOG.md

@@ -6,6 +6,11 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [unreleased]
 
+### Documentation:
+- Added `pdoc` template files to project inside `docs-templates` directory
+- Updated `build-docs` in Makefile to use `docs-templates` as the template directory while generating docs using `pdoc`
+- Updated `html.mako` template to have a single `h1` tag
+
 ## [0.10.0] - 2022-07-04
 
 - Update tests to cover `resend_code` feature in `passwordless` and `thirdpartypasswordless` recipe.

Makefile

@@ -41,4 +41,4 @@ with-flask:
 	pip3 install -e .[flask]
 
 build-docs:
-	rm -rf html && pdoc --html supertokens_python
+	rm -rf html && pdoc --html supertokens_python --template-dir docs-templates

docs-templates/_lunr_search.inc.mako

@@ -0,0 +1,50 @@
+<form>
+    <input id="lunr-search" name="q" placeholder="🔎 Search ..." aria-label="Search"
+           disabled minlength="2">
+</form>
+<link rel="preload stylesheet" as="style" href="https://cdnjs.cloudflare.com/ajax/libs/tingle/0.15.3/tingle.min.css" integrity="sha512-j1u8eUJ4f23xPPxwOrLUPQaCD2dwzNqqmDDcWS4deWsMv2ohLqmXXuP3hU7g8TyzbMSakP/mMqoNBYWj8AEIFg==" crossorigin>
+<script src="https://cdnjs.cloudflare.com/ajax/libs/tingle/0.15.3/tingle.min.js" integrity="sha512-plGUER9JkeEWPPqQBE4sdLqBoQug5Ap+BCGMc7bJ8BXkm+VVj6QzkpBz5Yv2yPkkq+cqg9IpkBaGCas6uDbW8g==" crossorigin></script>
+<style>
+    .modal-dialog iframe {
+        width: 100vw;
+        height: calc(100vh - 80px);
+    }
+    @media screen and (min-width: 700px) {
+        .modal-dialog iframe {
+            width: 70vw;
+            height: 80vh;
+        }
+    }
+    .modal-dialog .tingle-modal-box {width: auto;}
+    .modal-dialog .tingle-modal-box__content {padding: 0;}
+</style>
+<script>
+    const input = document.getElementById('lunr-search');
+    input.disabled = false;
+
+    input.form.addEventListener('submit', (ev) => {
+        ev.preventDefault();
+        const url = new URL(window.location);
+        url.searchParams.set('q', input.value);
+        history.replaceState({}, null, url.toString());
+        search(input.value);
+    });
+
+    ## On page load
+    const query = new URL(window.location).searchParams.get('q');
+    if (query)
+        search(query);
+
+    function search(query) {
+        const url = '${'../' * module.url().count('/')}doc-search.html#' + encodeURIComponent(query);
+        new tingle.modal({
+            cssClass: ['modal-dialog'],
+            onClose: () => {
+                const url = new URL(window.location);
+                url.searchParams.delete('q');
+                history.replaceState({}, null, url.toString());
+                setTimeout(() => input.focus(), 100);
+            }
+        }).setContent('<iframe src="' + url + '"></iframe>').open();
+    }
+</script>

docs-templates/config.mako

@@ -0,0 +1,64 @@
+<%!
+    # Template configuration. Copy over in your template directory
+    # (used with `--template-dir`) and adapt as necessary.
+    # Note, defaults are loaded from this distribution file, so your
+    # config.mako only needs to contain values you want overridden.
+    # You can also run pdoc with `--config KEY=VALUE` to override
+    # individual values.
+
+    html_lang = 'en'
+    show_inherited_members = False
+    extract_module_toc_into_sidebar = True
+    list_class_variables_in_index = True
+    sort_identifiers = True
+    show_type_annotations = True
+
+    # Show collapsed source code block next to each item.
+    # Disabling this can improve rendering speed of large modules.
+    show_source_code = True
+
+    # If set, format links to objects in online source code repository
+    # according to this template. Supported keywords for interpolation
+    # are: commit, path, start_line, end_line.
+    #git_link_template = 'https://github.com/USER/PROJECT/blob/{commit}/{path}#L{start_line}-L{end_line}'
+    #git_link_template = 'https://gitlab.com/USER/PROJECT/blob/{commit}/{path}#L{start_line}-L{end_line}'
+    #git_link_template = 'https://bitbucket.org/USER/PROJECT/src/{commit}/{path}#lines-{start_line}:{end_line}'
+    #git_link_template = 'https://CGIT_HOSTNAME/PROJECT/tree/{path}?id={commit}#n{start-line}'
+    git_link_template = None
+
+    # A prefix to use for every HTML hyperlink in the generated documentation.
+    # No prefix results in all links being relative.
+    link_prefix = ''
+
+    # Enable syntax highlighting for code/source blocks by including Highlight.js
+    syntax_highlighting = True
+
+    # Set the style keyword such as 'atom-one-light' or 'github-gist'
+    #     Options: https://github.com/highlightjs/highlight.js/tree/master/src/styles
+    #     Demo: https://highlightjs.org/static/demo/
+    hljs_style = 'github'
+
+    # If set, insert Google Analytics tracking code. Value is GA
+    # tracking id (UA-XXXXXX-Y).
+    google_analytics = ''
+
+    # If set, insert Google Custom Search search bar widget above the sidebar index.
+    # The whitespace-separated tokens represent arbitrary extra queries (at least one
+    # must match) passed to regular Google search. Example:
+    #google_search_query = 'inurl:github.com/USER/PROJECT  site:PROJECT.github.io  site:PROJECT.website'
+    google_search_query = ''
+
+    # Enable offline search using Lunr.js. For explanation of 'fuzziness' parameter, which is
+    # added to every query word, see: https://lunrjs.com/guides/searching.html#fuzzy-matches
+    # If 'index_docstrings' is False, a shorter index is built, indexing only
+    # the full object reference names.
+    #lunr_search = {'fuzziness': 1, 'index_docstrings': True}
+    lunr_search = None
+
+    # If set, render LaTeX math syntax within \(...\) (inline equations),
+    # or within \[...\] or $$...$$ or `.. math::` (block equations)
+    # as nicely-formatted math formulas using MathJax.
+    # Note: in Python docstrings, either all backslashes need to be escaped (\\)
+    # or you need to use raw r-strings.
+    latex_math = False
+%>