https://github.com/wildmountainfarms/solarthing-docs

Contains documentation for SolarThing to be displayed on readthedocs.io
https://github.com/wildmountainfarms/solarthing-docs

readthedocs solarthing

Last synced: 2 months ago
JSON representation

Contains documentation for SolarThing to be displayed on readthedocs.io

• Host: GitHub
• URL: https://github.com/wildmountainfarms/solarthing-docs
• Owner: wildmountainfarms
• Created: 2021-12-19T21:54:00.000Z (about 3 years ago)
• Default Branch: main
• Last Pushed: 2024-05-01T16:17:43.000Z (8 months ago)
• Last Synced: 2024-05-02T11:17:59.445Z (8 months ago)
• Topics: readthedocs, solarthing
• Language: Shell
• Homepage: https://solarthing.readthedocs.io
• Size: 979 KB
• Stars: 1
• Watchers: 2
• Forks: 2
• Open Issues: 3
• Metadata Files:
  • Readme: README.rst

Awesome Lists containing this project

README

        
SolarThing Documentation Repository

=======================================

This repository contains documentation for SolarThing that can be viewed on https://solarthing.readthedocs.io

Main repository at https://github.com/wildmountainfarms/solarthing

If you are unfamiliar with RST, this is a good reference: https://thomas-cokelaer.info/tutorials/sphinx/rest_syntax.html

Building

----------

To build this yourself, run these commands:

.. code-block:: shell

    cd docs/

    python3 -m venv .venv

    source .venv/bin/activate

    pip install -r source/requirements.txt

    make html

    xdg-open "file://$(pwd)/build/html/index.html"

    make latexpdf  # requires latexmk command

    make epub

Dependencies

-------------

Depending on what you want to build yourself from the Building section, you can run these commands to install some or all of the dependencies.

.. code-block:: shell

    apt install python3 python3-pip latexmk

Stuff we might use in the future:

* https://www.sphinx-doc.org/en/master/usage/extensions/linkcode.html

Testing

----------

Running the docker container is optional.

.. code-block:: console

  docs/preview.sh && docker compose restart

Accessing content via the webserver has some benefits rather than just viewing the html file in your browser:

* Cookies are stored across the entire site, so...

  * Tab selection across pages is kept

TODO

---------

* Find a way to get GraphQL syntax highlighting into pygments

  * Waiting on a release. As this issue is merged: https://github.com/pygments/pygments/pull/2428

* Find a way to get JSON5 syntax highlighting into pygments. Or, alternatively, just regular JSON highlighting with the ability to ignore stuff that's not JSON syntax

* Page about common errors including permission issues

* Page about using socat and about configuring timeouts

About These Docs

-------------------

July 27, 2023

^^^^^^^^^^^^^^

We stopped using `sphinx_rtd_theme `_ because of this: https://github.com/readthedocs/sphinx_rtd_theme/issues/1463.

We want Sphinx 7 support!

That issue referred me to `furo `_, a theme that impressed me when I first looked at it.

After trying it out, I couldn't be happier. Dark/light mode support out of the box, and just a better user experience.