Skip to content

Commit

Permalink
Small fixes to developer documentation (#258)
Browse files Browse the repository at this point in the history
* Mention option to develop on windows.

* How to run Documentation locally

* Revert "How to run Documentation locally"

This reverts commit 75892ae.

* The docs are build automatically.
  • Loading branch information
jscheidtmann authored Dec 18, 2024
1 parent 7543caa commit 3e4730f
Showing 1 changed file with 21 additions and 6 deletions.
27 changes: 21 additions & 6 deletions docs/source/dev_guide.rst
Original file line number Diff line number Diff line change
Expand Up @@ -54,15 +54,26 @@ the procedure. If not, here is how you do this:
* `Youtube - How To Pull Request in 3 Minutes <https://www.youtube.com/watch?v=jRLGobWwA3Y>`_

Documentation
.............
-------------

The `PiFinder documentation <https://pifinder.readthedocs.io/en/release/index.html>`_
is written in `reStructuredText <https://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html#external-links>`_ .
The files are located in PiFinders GitHub repository under ``docs`` and have
the ending ``.rst``. Many open source projects use `redthedocs.io <eadthedocs.io>`
for creating documentation since it is immediately generated, when you are committing
the GitHub code (CI/CD pipeline). It is very easy to link your fork of the documentation
code to GitHub.
The files are located in PiFinders GitHub repository under ``docs/source`` and have
the ending ``.rst``. The documentation is then published to `redthedocs.io <eadthedocs.io>`_, when the change is committed
to the official GitHub repository (using readthedocs's infrastructure).

You can link your fork also to your account on readthedocs.io, but it is easier to build the documentation locally.
For this install sphinx using pip:

.. code-block::
pip install -r sphinx sphinx_rtd_theme
You can then use the supplied ``Makefile`` to build a html tree using ``make html`` and running a http server in the directory with the files:

.. code-block::
cd build/html; python -m http.server
Setup the development environment
Expand All @@ -89,6 +100,10 @@ You can also develop on any Posix compatible system (Linux / MacOS) in roughly t
same way you can on a Raspberry Pi. The emulated hardware and networking features
will work differently so this is mostly useful for UI/Catalog feature development.

Note that you can develop on Windows by activating Windows Subsystem for Linux (WSL2)
and installing Ubuntu from the Microsoft Store. The window launched by PiFinder will
be fully integrated into your windows desktop.

To get started, fork the repo and set up your virtual environment system of choice
using Python 3.9. Then follow some of the steps below!

Expand Down

0 comments on commit 3e4730f

Please sign in to comment.