Add mkdocs documentation site

Author: Patrick Kidger Bot

.github/workflows/build_docs.yml

@@ -0,0 +1,37 @@
+name: Build docs
+
+on:
+  push:
+    branches:
+      - main
+
+jobs:
+  build:
+    strategy:
+      matrix:
+        python-version: [ 3.11 ]
+        os: [ ubuntu-latest ]
+    runs-on: ${{ matrix.os }}
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v2
+
+      - name: Set up Python ${{ matrix.python-version }}
+        uses: actions/setup-python@v2
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Install dependencies
+        run: |
+          python -m pip install --upgrade pip
+          python -m pip install '.[docs]'
+
+      - name: Build docs
+        run: |
+          mkdocs build
+
+      - name: Upload docs
+        uses: actions/upload-artifact@v4
+        with:
+          name: docs
+          path: site  # where `mkdocs build` puts the built site

.github/workflows/run_tests.yml

@@ -23,7 +23,7 @@ jobs:
       - name: Install dependencies
         run: |
           python -m pip install --upgrade pip
-          python -m pip install '.[dev,tests]'
+          python -m pip install '.[dev,docs,tests]'
 
       - name: Checks with pre-commit
         run: |
@@ -32,3 +32,7 @@ jobs:
       - name: Test with pytest
         run: |
           pytest
+
+      - name: Check that documentation can be built.
+        run: |
+          mkdocs build

CONTRIBUTING.md

@@ -38,3 +38,16 @@ git push
 
 Finally, open a pull request on GitHub!
 
+---
+
+**If you're making changes to the documentation:**
+
+Make your changes. You can then build the documentation by doing
+
+```bash
+pip install -e '.[docs]'
+mkdocs serve
+```
+
+You can then see your local copy of the documentation by navigating to `localhost:8000` in a web browser.
+

docs/.htaccess

@@ -0,0 +1 @@
+ErrorDocument 404 /tinyio/404.html

docs/_overrides/partials/source.html

@@ -0,0 +1,23 @@
+{% import "partials/language.html" as lang with context %}
+<a href="{{ config.repo_url }}" title="{{ lang.t('source.link.title') }}" class="md-source" data-md-component="source">
+  <div class="md-source__icon md-icon">
+    {% set icon = config.theme.icon.repo or "fontawesome/brands/git-alt" %}
+    {% include ".icons/" ~ icon ~ ".svg" %}
+  </div>
+  <div class="md-source__repository">
+    {{ config.repo_name }}
+  </div>
+</a>
+<a href="{{ config.theme.twitter_url }}" title="Go to Twitter" class="md-source">
+  <div class="md-source__icon md-icon">
+    {% include ".icons/fontawesome/brands/twitter.svg" %}
+  </div>
+</a>
+<a href="{{ config.theme.bluesky_url }}" title="Go to Bluesky" class="md-source">
+  <div class="md-source__icon md-icon">
+    {% include ".icons/fontawesome/brands/bluesky.svg" %}
+  </div>
+  <div class="md-source__repository">
+    {{ config.theme.twitter_bluesky_name }}
+  </div>
+</a>

docs/_static/custom_css.css

@@ -0,0 +1,172 @@
+/* Fix /page#foo going to the top of the viewport and being hidden by the navbar */
+html {
+    scroll-padding-top: 50px;
+}
+
+/* Fit the Twitter handle alongside the GitHub one in the top right. */
+
+div.md-header__source {
+    width: revert;
+    max-width: revert;
+}
+
+a.md-source {
+    display: inline-block;
+}
+
+.md-source__repository {
+    max-width: 100%;
+}
+
+/* Emphasise sections of nav on left hand side */
+
+nav.md-nav {
+  padding-left: 5px;
+}
+
+nav.md-nav--secondary {
+    border-left: revert !important;
+}
+
+.md-nav__title {
+  font-size: 0.9rem;
+}
+
+.md-nav__item--section > .md-nav__link {
+  font-size: 0.9rem;
+}
+
+/* Indent autogenerated documentation */
+
+div.doc-contents {
+  padding-left: 25px;
+  border-left: 4px solid rgba(230, 230, 230);
+}
+
+/* Increase visibility of splitters "---" */
+
+[data-md-color-scheme="default"] .md-typeset hr {
+    border-bottom-color: rgb(0, 0, 0);
+    border-bottom-width: 1pt;
+}
+
+[data-md-color-scheme="slate"] .md-typeset hr {
+    border-bottom-color: rgb(230, 230, 230);
+}
+
+/* More space at the bottom of the page */
+
+.md-main__inner {
+  margin-bottom: 1.5rem;
+}
+
+/* Remove prev/next footer buttons */
+
+.md-footer__inner {
+    display: none;
+}
+
+/* Change font sizes */
+
+html {
+    /* Decrease font size for overall webpage
+       Down from 137.5% which is the Material default */
+    font-size: 110%;
+}
+
+.md-typeset .admonition {
+    /* Increase font size in admonitions */
+    font-size: 100% !important;
+}
+
+.md-typeset details {
+    /* Increase font size in details */
+    font-size: 100% !important;
+}
+
+.md-typeset h1 {
+    font-size: 1.6rem;
+}
+
+.md-typeset h2 {
+    font-size: 1.5rem;
+}
+
+.md-typeset h3 {
+    font-size: 1.3rem;
+}
+
+.md-typeset h4 {
+    font-size: 1.1rem;
+}
+
+.md-typeset h5 {
+    font-size: 0.9rem;
+}
+
+.md-typeset h6 {
+    font-size: 0.8rem;
+}
+
+/* Bugfix: remove the superfluous parts generated when doing:
+
+??? Blah
+
+    ::: library.something
+*/
+
+.md-typeset details .mkdocstrings > h4 {
+    display: none;
+}
+
+.md-typeset details .mkdocstrings > h5 {
+    display: none;
+}
+
+/* Change default colours for <a> tags */
+
+[data-md-color-scheme="default"] {
+    --md-typeset-a-color: rgb(0, 189, 164) !important;
+}
+[data-md-color-scheme="slate"] {
+    --md-typeset-a-color: rgb(0, 189, 164) !important;
+}
+
+/* Highlight functions, classes etc. type signatures. Really helps to make clear where
+   one item ends and another begins. */
+
+[data-md-color-scheme="default"] {
+    --doc-heading-color: #DDD;
+    --doc-heading-border-color: #CCC;
+    --doc-heading-color-alt: #F0F0F0;
+}
+[data-md-color-scheme="slate"] {
+    --doc-heading-color: rgb(25,25,33);
+    --doc-heading-border-color: rgb(25,25,33);
+    --doc-heading-color-alt: rgb(33,33,44);
+    --md-code-bg-color: rgb(38,38,50);
+}
+
+h4.doc-heading {
+    /* NOT var(--md-code-bg-color) as that's not visually distinct from other code blocks.*/
+    background-color: var(--doc-heading-color);
+    border: solid var(--doc-heading-border-color);
+    border-width: 1.5pt;
+    border-radius: 2pt;
+    padding: 0pt 5pt 2pt 5pt;
+}
+h5.doc-heading, h6.heading {
+    background-color: var(--doc-heading-color-alt);
+    border-radius: 2pt;
+    padding: 0pt 5pt 2pt 5pt;
+}
+
+/* Fix spurious whitespace at the end of mkdocstrings output */
+
+div.output_wrapper > div.output > div.output_area > div.output_subarea > pre {
+    white-space: normal;
+}
+
+div.output_wrapper > div.output > div.output_area > div.output_subarea > pre > code {
+    white-space: pre;
+}

docs/_static/favicon.png

@@ -0,0 +1,16 @@
+window.MathJax = {
+  tex: {
+    inlineMath: [["\\(", "\\)"]],
+    displayMath: [["\\[", "\\]"]],
+    processEscapes: true,
+    processEnvironments: true
+  },
+  options: {
+    ignoreHtmlClass: ".*|",
+    processHtmlClass: "arithmatex"
+  }
+};
+
+document$.subscribe(() => { 
+  MathJax.typesetPromise()
+})

docs/_static/mathjax.js

@@ -0,0 +1,26 @@
+# Asynchronous context managers
+
+You can use the following pattern to implement context managers with asynchronous entry:
+
+```python
+def my_coro():
+    with (yield my_context_manager(x=5)) as val:
+        print(f"Got val {val}")
+```
+where:
+```python
+def my_context_manager(x):
+    print("Initialising...")
+    yield tinyio.sleep(1)
+    print("Initialised")
+    return make_context_manager(x)
+
+@contextlib.contextmanager
+def make_context_manager(x):
+    try:
+        yield x
+    finally:
+        print("Cleaning up")
+```
+
+This isn't anything fancier than just using a coroutine that returns a regular `with`-compatible context manager. See the source code for [`tinyio.Semaphore`][] for an example of this pattern.

docs/api/async_context_managers.md

@@ -0,0 +1,27 @@
+# Asynchronous iterators
+
+You can use the following pattern to implement asynchronous iterators:
+
+```python
+def my_coro():
+    for x in slow_range(5):
+        x = yield x
+        print(f"Got {x}")
+```
+where:
+```python
+def slow_range(x):  # this function is an iterator-of-coroutines
+    for i in range(x):
+        yield slow_range_i(i)  # this `yield` statement is seen by the `for` loop
+
+def slow_range_i(i):  # this function is a coroutine
+    yield tinyio.sleep(1)  # this `yield` statement is seen by the `tinyio.Loop()`
+    return i
+```
+
+Here we just have `yield` being used in a couple of different ways that you're already used to:
+
+- as a regular Python generator/iterator;
+- as a `tinyio` coroutine.
+
+For an example of this, see the source code for [`tinyio.as_completed`][].