Merge pull request #14 from pradyunsg/add-some-components

docs/usage/components/breadcrumbs.md

@@ -0,0 +1,32 @@
+# Breadcrumbs
+
+A breadcrumb navigation provide links back to each "parent" page of the
+current page, showing the user's current location in a website and
+giving them a good way to navigate within it.
+
+## Usage
+
+```jinja
+{% include "components/breadcrumbs.html" %}
+```
+
+When the page does not have "parent" pages (in the top-level of the hierarchy), this will be empty.
+
+In all other cases, the structure looks like:
+
+- a single `nav.breadcrumb-nav`
+  - a single `ol.breadcrumb-nav-list`
+    - one-or-more `breadcrumb-nav-list-item` containing a single
+      `a[href]` tag.
+    - a single `breadcrumb-nav-list-item` contain a single `span` tag.
+
+```{tip}
+See [this page][w3schools-breadcrumbs] for an example of how to stylise
+breadcrumbs with this structure.
+```
+
+## Configurability
+
+None.
+
+[w3schools-breadcrumbs]: https://www.w3schools.com/howto/howto_css_breadcrumbs.asp

docs/usage/components/edit-this-page.md

@@ -0,0 +1,43 @@
+# "Edit this page" link
+
+It is fairly common for technical documentation websites to contain a
+link to edit the original sources of a page. This makes it easy for a
+reader to quickly fix a typo and provides a decent way to navigate to
+the source repository of the project.
+
+## Usage
+
+```jinja
+{% include "components/edit-this-page.html" %}
+```
+
+This will add a single `a[href]` tag, with the text "Edit this page".
+
+You also need to declare the following in `theme.conf`'s `options`
+section:
+
+```ini
+source_repository =
+source_branch =
+source_directory =
+```
+
+## Configurability
+
+None, for the theme authors. If the theme author overrides this
+component, they can depend on the macro `determine_page_edit_link` to
+get the relevant URL.
+
+The documentation author can set values in their `conf.py` file using
+`html_theme_options`:
+
+```python
+html_theme_options = {
+  "source_repository": "https://github.com/pradyunsg/sphinx-basic-ng/",
+  "source_branch": "main",
+  "source_directory": "docs/",
+}
+```
+
+Those user-provided values are used to determine the link for editting
+the generated page on the hosting platform.

docs/usage/components/ethical-ads.md

@@ -0,0 +1,46 @@
+# Ethical Ads
+
+A lot of Sphinx documentation is hosted on [ReadTheDocs], who provide
+free docs hosting for open source projects. [Ethical Ads] is a
+privacy-respecting ad network built by ReadTheDocs, and is one of the
+contributors to their sustainability.
+
+Adding this component to your page in the correct places, helps you make
+sure that when ReadTheDocs tries to show ethical ads in documentation
+built with your theme, they are well integrated with it and show up
+where you expect them to be visible.
+
+## Usage
+
+```jinja
+{% include "components/ethical-ads.html" %}
+```
+
+It is also expected that the page will [manually load ads]. This is done
+for pages hosted by ReadTheDocs automatically.
+
+## Configurability
+
+There are 3 values that can be provided via the html-context, which
+correspond to the following configuration attributes on the ethical ad
+`div`:
+
+- `ethical_ad_class`: maps to `class`
+- `ethical_ad_type`: maps to `data-ea-type`
+- `ethical_ad_publisher`: maps to `data-ea-publisher`
+
+If these values are not set, they will take reasonable values for
+ReadTheDocs-based documentation.
+
+The `div` for the ad is only included on the page if the documentation
+is being built on ReadTheDocs or `ethical_ad_publisher` is set.
+
+```{tip}
+If you need additional control/configuration, it is recommended to
+include the this component as shown here, and to override the
+`components/ethical-ads.html` file in your theme.
+```
+
+[ReadTheDocs]: https://readthedocs.org/
+[Ethical Ads]: https://www.ethicalads.io/
+[manually load ads]: https://ethical-ad-client.readthedocs.io/en/latest/#manually-loading-ads

docs/usage/components/index.md

@@ -2,16 +2,11 @@
 
 This section describes all of the components provided by this theme.
 
-```{todo}
-Provide a general overview of how components can be used, overridden and
-customised.
-```
-
-```{todo}
-Write each component as a reference section, describing what it does 
-followed by how-to-{use,customise} sections.
-```
-
 ```{toctree}
 :maxdepth: 1
+
+breadcrumbs
+edit-this-page
+ethical-ads
+logo
 ```

docs/usage/components/logo.md

@@ -0,0 +1,18 @@
+# Site Logo
+
+Sphinx allows users to set a logo for their site, using the
+[`html_logo`][sphinx-html_logo] variable in `conf.py`. Themes are
+expected to have this on the page, if provided by the user.
+
+## Usage
+
+```jinja
+{% include "components/logo.html" %}
+```
+
+If the logo is set, this adds an `img.site-logo` with the correct URL
+for the logo. Otherwise, this is empty.
+
+## Configurability
+
+None.

src/sphinx_basic_ng/theme/basic-ng/components/breadcrumbs.html

@@ -0,0 +1,14 @@
+{% if parents %}
+<nav aria-label="Breadcrumb" class="breadcrumb-nav">
+  <ol class="breadcrumb-nav-list">
+    {% for item in parents %}
+    <li class="breadcrumb-nav-list-item">
+      <a href="{{ item.link }}">{{ item.title }}</a>
+    </li>
+    {% endfor %}
+    <li class="breadcrumb-nav-list-item">
+      <span>{{ title }}</span>
+    </li>
+  </ol>
+</nav>
+{% endif %}

src/sphinx_basic_ng/theme/basic-ng/components/edit-this-page.html

@@ -0,0 +1,44 @@
+{%- macro sanitise_trailing_slash(s) -%}{{ s.rstrip("/") }}{%- endmacro -%}
+
+{%- macro determine_page_edit_link() -%}
+  {#- First, sanitise the trailing slashes. -#}
+  {%- set repo = sanitise_trailing_slash(theme_source_repository) -%}
+  {%- set branch = theme_source_branch -%}
+  {%- set subdirectory = sanitise_trailing_slash(theme_source_directory) -%}
+
+  {#- Figure out the document's source file path. -#}
+  {%- set relative_path = pagename + page_source_suffix -%}
+  {%- if not subdirectory -%}
+    {%- set document_path = relative_path -%}
+  {%- else -%}
+    {%- set document_path = subdirectory + "/" + relative_path -%}
+  {%- endif -%}
+
+  {#- Don't allow http:// URLs -#}
+  {%- if repo.startswith(
+    (
+      "http://github.com/",
+      "http://gitlab.com/",
+      "http://bitbucket.org/",
+    )
+  ) -%}
+    {{ warning("Could not use `source_repository` provided. Please use https:// links in your `conf.py` file's `html_theme_options`.") }}
+  {#- Handle the relevant cases -#}
+  {%- elif repo.startswith("https://github.com/") -%}
+    {{ repo }}/edit/{{ branch }}/{{ document_path }}
+  {%- elif repo.startswith("https://gitlab.com/") -%}
+    {{ repo }}/-/edit/{{ branch }}/{{ document_path }}
+  {%- elif repo.startswith("https://bitbucket.org/") -%}
+    {{ repo }}/src/{{ branch }}/{{ document_path }}?mode=edit&at={{ branch }}
+  {#- Fail with a warning -#}
+  {%- else -%}
+    {{ warning("Could not understand `source_repository` provided: " + repo) }}
+  {%- endif -%}
+{%- endmacro -%}
+
+{%- if theme_source_repository -%}
+  {%- if not theme_source_branch -%}
+    {{ warning("Provided `source_repository` but not `source_branch`. ")}}
+  {%- endif -%}
+  <a href="{{ determine_page_edit_link() }}">{{ _("Edit this page") }}</a>
+{%- endif -%}

src/sphinx_basic_ng/theme/basic-ng/components/ethical-ads.html

@@ -0,0 +1,9 @@
+{% if READTHEDOCS or ethical_ad_publisher %}
+<div
+  id="ethical-ad-placement"
+  class="{{ ethical_ad_class|default('flat') }}"
+  data-ea-publisher="{{ ethical_ad_publisher|default('readthedocs-sidebar') }}"
+  data-ea-type="{{ ethical_ad_type|default('readthedocs-sidebar') }}"
+  data-ea-manual="true"
+></div>
+{% endif %}

src/sphinx_basic_ng/theme/basic-ng/components/logo.html

@@ -0,0 +1,3 @@
+{% if logo %}
+<img class="site-logo" src="{{ pathto('_static/' + logo, 1) }}" alt="Logo"/>
+{% endif %}

src/sphinx_basic_ng/theme/basic-ng/sections/article-main.html

@@ -1,3 +1 @@
 sections/article-main.html
-
-{{ body }}

src/sphinx_basic_ng/theme/basic-ng/sections/sidebar-primary.html

@@ -1,3 +1 @@
 sections/sidebar-primary.html
-
-{{ toc }}

tests/barebones/conf.py

@@ -22,3 +22,4 @@
 #
 
 html_theme = "basic-ng"
+templates_path = ["_templates"]

tests/barebones/index.md

@@ -11,12 +11,12 @@ Below is a sample Table of Contents.
 ```{toctree}
 :glob:
 
-section-one/*
+section-one/index
 ```
 
 ```{toctree}
 :glob:
-:caption: Section 2
+:caption: Caption
 
-section-two/*
+section-two/index
 ```

tests/barebones/section-one/index.md

@@ -0,0 +1,6 @@
+# Section 1
+
+```{toctree}
+page-one-one
+page-one-two
+```

tests/barebones/section-two/index.md

@@ -0,0 +1,6 @@
+# Section 2
+
+```{toctree}
+page-two-one
+page-two-two
+```