update 0af43cb

.buildinfo

@@ -0,0 +1,4 @@
+# Sphinx build info version 1
+# This file hashes the configuration used when building these files. When it is not found, a full rebuild will be done.
+config: 48c5e6dbe33e39badd283d3fdeab93fc
+tags: 645f666f9bcd5a90fca523b33c5a78b7

_sources/cli/themes.rst.txt

@@ -0,0 +1,73 @@
+.. program:: btd
+
+Supported themes
+################
+
+BTD can be used with any Sphinx theme. Hence, users of ``alabaster``, ``sphinx_rtd_theme`` or others should find no relevant
+difference between using BTD or building the documentation using a different procedure.
+
+However, some features of ``sphinx_rtd_theme`` are undocumented and rely on the theme being used on RTD's own service. BTD
+easens the transition from RTD to GitHub Pages (or any other host) by automatically creating a ``context.json`` with the
+fields/data extracted from the context (envvars, workflow, etc.). In order to add the context, the recommended procedure
+is using the following snippet in the `conf.py` file:
+
+.. code-block:: python
+
+    from json import loads
+    from pathlib import Path
+
+.. code-block:: python
+
+    html_context = {}
+
+    ctx = Path(__file__).resolve().parent / 'context.json'
+    if ctx.is_file():
+        html_context.update(loads(ctx.open('r').read()))
+
+`buildthedocs/sphinx.theme <https://github.com/buildthedocs/sphinx.theme>`_
+===========================================================================
+
+As explained in `docs.readthedocs.io: Unsupported <https://docs.readthedocs.io/en/latest/open-source-philosophy.html#official-support>`_,
+usage of RTD's theme outside of the RTD service is unsupported *because it doesn't further* their *goal of promoting documentation in the Open Source Community*.
+`buildthedocs/sphinx.theme <https://github.com/buildthedocs/sphinx.theme>`_ is a fork of ``sphinx_rtd_theme`` meant to be used
+on any host. Apart from ensuring that it works on GitHub Pages, some aesthetical modifications are included:
+
+- Set default pygments style to ``stata-dark``.
+- Adjust header and footer ``hr`` margins.
+- Reduce the base font size from 16px to 15px.
+- Adjust the colour and search box of the sidebar.
+- Justify paragraphs and list items.
+- Reduce margins in lists.
+- Hide h1 (shown in the breadcrumbs and in the sidebar).
+- Underline h2 headers.
+- Add option ``home_breadcrumbs``.
+- Align content of the footer.
+
+As explained in `buildthedocs/sphinx.theme: README <https://github.com/buildthedocs/sphinx.theme#build-the-docs-sphinx-theme>`_,
+the BTD theme is not distributed as a pip package. Users need to clone/download the theme and extract it to a given path.
+Fortunately, BTD does it automatically as long as field ``theme`` is set in :btdrepo:`.btd.yml <.btd.yml>`. This feature might
+be used for providing any custom theme.
+
+BTD downloads and extracts the theme in a subdir ``_theme`` in the root of the input sources. Hence, theme related
+options in the ``conf.py`` file should look like the following snippet:
+
+.. code-block:: python
+
+    html_theme_options = {
+        'logo_only': True,
+        'home_breadcrumbs': False,
+        'vcs_pageview_mode': 'blob',
+    }
+
+    html_theme_path = ["."]
+    html_theme = "_theme"
+
+Find further details about theme options at `buildthedocs.github.io/sphinx.theme/configuring <https://buildthedocs.github.io/sphinx.theme/configuring.html>`_.
+
+.. HINT:: For testing the theme locally by calling Sphinx directly (without BTD), retrieve the theme and extract it to `doc/_theme`.
+
+Other themes to keep an eye on
+==============================
+
+* `pradyunsg/furo <https://github.com/pradyunsg/furo>`__
+* `sphinxthemes.com <https://sphinxthemes.com/>`__

_sources/cli/usage.rst.txt

@@ -0,0 +1,34 @@
+.. program:: btd
+
+Usage
+#####
+
+Most of the features are not exposed through CLI yet. A YAML configuration file is used instead. Copy
+:btdrepo:`.btd.yml <.btd.yml>` to your repository and follow the instructions inside for customising it to your use case.
+When ``cli.py run`` is executed, the config file is expected to exist in ``$pwd/.btd.yml``.
+
+- If available, BTD uses a ``Makefile`` located in the root of the input sources. A ``Makefile`` is typically created
+  by Sphinx when a new project is generated.
+
+- Optionally, a ``requirements.txt`` can be defined in the root of the input sources. Unless some custom container image is
+  used, documentation dependencies should be described using this mechanism.
+
+.. NOTE:: The CLI tool is written using `pyAttributes <https://github.com/Paebbels/pyAttributes>`_. Hence, command/option
+  ``--help`` provides information about available commands. However, as said, most options are not exposed yet.
+
+Local execution
+===============
+
+The CLI tool is currently meant for execution in GitHub Actions workflows. Therefore, some parameters are expected to be
+given as environment variables:
+
+- ``INPUT_CONFIG``: path to the BTD configuration file.
+- ``INPUT_TOKEN``: token for authenticated access to GitHub (for pushing sites).
+- ``GITHUB_REPOSITORY``: the repository where results are to be pushed.
+- ``GITHUB_SHA``: the commit SHA, used for linking a publication with the sources.
+- ``GITHUB_REF``: use in the context for providing *Edit on GitHub* links.
+
+For testing the tool locally, users might want to specify those environment variables manually.
+
+.. NOTE:: Supporting these parameters as proper CLI arguments is desired but not implemented yet. Should you want to help,
+  contributions are welcome!

_sources/gha/action.rst.txt

@@ -0,0 +1,22 @@
+.. program:: btd
+
+Docker GitHub Action
+####################
+
+The most straightforward usage of BTD is as a GitHub Action. Three options are accepted:
+
+- ``config``: path to the BTD configuration file (default ``.btd.yml``).
+- ``token``: token for making authenticated API calls (optional, ``${{ github.token }}`` is available by default).
+- ``skip-deploy``: whether to push the docs or to just build them.
+
+.. code-block:: yaml
+
+    - uses: buildthedocs/btd@v0
+      with:
+        token: ${{ github.token }}
+
+See a complete workflow in :ref:`btd:workflow`.
+
+.. IMPORTANT:: If parameter ``token`` is not provided, the Action will try to upload the results (typically to branch
+  ``gh-pages``) using the default token.
+  Use ``skip-deploy`` to prevent results being uploaded.

_sources/gha/examples.rst.txt

@@ -0,0 +1,19 @@
+.. program:: btd
+
+.. _btd:examples:
+
+Examples
+########
+
+:gh:`ghdl/ghdl-cosim` showcases the typical usage of BTD.
+
+In :gh:`ghdl/ghdl`, a different HTML documentation generator is executed before BTD.
+The content to be included in the final site is placed in a subdir, which is specified in the Sphinx configuration file
+(``doc.py``).
+For instance:
+
+.. code-block::
+
+    html_extra_path = [str(Path(__file__).resolve().parent.parent / 'public')]
+
+See `html_extra_path <https://www.sphinx-doc.org/en/master/usage/configuration.html#confval-html_extra_path>`_.

_sources/gha/workflow.rst.txt

@@ -0,0 +1,55 @@
+.. program:: btd
+
+.. _btd:workflow:
+
+GitHub Action workflow
+######################
+
+The following YAML snippet is a minimal GitHub Actions workflow. Enable BTD in a repository by copying it to ``.github/workflows/``.
+
+.. code-block:: yaml
+
+    name: 'doc'
+
+    on:
+      push:
+
+    jobs:
+
+      linux:
+        runs-on: ubuntu-latest
+        steps:
+
+        - uses: actions/checkout@v2
+
+        - uses: buildthedocs/btd@v0
+          with:
+            token: ${{ github.token }}
+
+        - uses: actions/upload-artifact@v2
+          with:
+            name: source
+            path: source/_build/html
+
+Since the (optional) ``token`` is provided, BTD will automatically upload the documentation to branch ``gh-pages`` (or the
+target specified in :btdrepo:`.btd.yml <.btd.yml>`). Then, it will be available at ``https://USERNAME.github.io/REPOSITORY``.
+
+Using ``actions/upload-artifact`` is optional too. As the name implies, it uploads the results of the workflow as a zipfile.
+This might be useful for testing purposes, or in PRs. That is, for building the documentation in CI and checking the results,
+without overwriting the *production* site.
+
+.. IMPORTANT:: If branch ``gh-pages`` does not exist and GitHub Actions creates it, the publication won't be triggered.
+  An owner of the repository needs to push to the branch, once at least, for publication to be enabled. Further updates
+  by GitHub Actions will be properly picked.
+
+  Some users might want to create branch ``gh-pages`` (with some dummy content), before using BTD for the first time. Others
+  might use the following snippet for reseting the author:
+
+  .. code-block:: shell
+
+      git checkout -b gh-pages origin/gh-pages
+      git commit --amend --reset-author
+      git push origin +gh-pages
+
+.. IMPORTANT:: BTD will always create a branch with a single commit and then overwrite any existing content in ``gh-pages``
+  (by force-pushing). In :ref:`btd:examples` there are references about how to add content to the site, before running BTD.

_sources/index.rst.txt

@@ -0,0 +1,55 @@
+.. program:: btd
+
+Build The Docs's documentation!
+###############################
+
+.. image:: _static/logo.png
+   :width: 175 px
+   :align: center
+   :target: https://github.com/buildthedocs/btd
+
+.. raw:: html
+
+    <p style="text-align: center;">
+      <a title="GitHub Repository" href="https://github.com/buildthedocs/btd"><img src="https://img.shields.io/badge/-buildthedocs/btd-323131.svg?longCache=true&style=flat-square&logo=github"></a><!--
+      -->
+      <a title="Join the chat at https://gitter.im/buildthedocs/community" href="https://gitter.im/buildthedocs/community"><img src="https://img.shields.io/badge/chat-on%20gitter-4db797.svg?longCache=true&style=flat-square&logo=gitter&logoColor=e8ecef"></a><!--
+      -->
+    </p>
+
+    <hr>
+
+This is the documentation of Build The Docs (BTD). BTD is a Python CLI tool for building documentation sites with static
+site generators and (optionally) uploading the output to git repositories. For easing the utilisation in GitHub Actions
+workspaces, a Docker Action is also provided. The Action wraps the CLI tool in a container and sets most parameters based
+on the context.
+
+
+.. toctree::
+   :hidden:
+   :caption: Command-Line Interface
+
+   cli/usage
+   cli/themes
+
+
+.. toctree::
+   :hidden:
+   :caption: GitHub Actions
+
+   gha/action
+   gha/workflow
+   gha/examples
+
+
+.. toctree::
+   :hidden:
+   :caption: Appendix
+
+   similar_projects
+   references
+
+
+..  * :ref:`genindex`
+  * :ref:`modindex`
+  * :ref:`search`

_sources/references.rst.txt

@@ -0,0 +1,6 @@
+References
+##########
+
+* :gh:`pietroalbini/buildthedocs`
+* :gh:`Robpol86/sphinxcontrib-versioning`
+* :gh:`peaceiris/actions-gh-pages`

_sources/similar_projects.rst.txt

@@ -0,0 +1,26 @@
+Similar projects
+################
+
+ReadTheDocs.org (RTD.org)
+=========================
+
+This project (BTD) started as an alternative to `readthedocs.org <https://readthedocs.org/>`__ (RTD.org) for users
+that don't need most of the features that RTD.org provides as a service (webhooks, user/team/project management, web
+frontend or API to modify settings, etc), because they use a different web hosting service and a CI service, such as,
+GitHub Pages and GitHub Actions.
+See :gh:`rtfd/readthedocs-build#35 <rtfd/readthedocs-build/issues/35>`.
+
+buildthedocs.pietroalbini.org
+=============================
+
+There is a Python package with the same name as this project: :gh:`pietroalbini/buildthedocs`.
+The development of both projects is independent ATM, but the same name is used because both tools are meant for the same
+exact usage.
+Differences are found in implementation details:
+
+* The Python package is expected to be executed natively or inside a VM/container which has all the required
+  dependencies pre-installed.
+
+* This project is expected to be executed either natively or in CI jobs with `docker <https://www.docker.com/>`__.
+  Multiple `docker images <https://hub.docker.com/u/btdi/>`__ with pre-installed dependencies are used to provide
+  ready-to-use environments for each task.