Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Add camel case API #9

Merged
merged 20 commits into from
Jun 21, 2022
Merged
Changes from 1 commit
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
Prev Previous commit
Next Next commit
update building docs info & hide ToC on landing pg
2bndy5 committed Jun 15, 2022
commit 07fc63681ba1c12991e4d83f532b7d440d263093
86 changes: 37 additions & 49 deletions README.rst
Original file line number Diff line number Diff line change
@@ -113,13 +113,13 @@ same version of CPython, CPU architecture, and C standard lib.
rm -r _skbuild/

3. To install a built wheel, simply pass the wheel's path and file name to ``pip install``:

.. code-block:: bash

python -m pip install dist/pyrf24-MAJOR.MINOR.PATCH-cp3X-cp3X-linux_ARCH.whl

Where the following would be replaced accordingly:

- ``MAJOR.MINOR.PATCH`` is the current version of the pyrf24 package
- ``cp3X`` is the version of python used to build the wheel (ie ``cp39`` for CPython 3.9)
The second occurrence of ``cp3X`` describes the CPython ABI compatibility.
@@ -147,7 +147,7 @@ Some of the C++ functions that do not accept arguments are wrapped as a class pr
style functions are still exposed. For example:

.. code-block:: py

radio.listen = False
# is equivalent to
radio.stopListening() # not documented
@@ -167,67 +167,55 @@ Documentation
~~~~~~~~~~~~~

Before submitting contributions, you should make sure that any documentation changes builds
successfully. This can be done locally.

Documentation Dependencies
--------------------------
successfully. This can be done locally but **on Linux only**. The documentation of API requires
this package (& all its latest changes) be installed.

This package's documentation is built with the python package Sphinx and the sphinx-immaterial theme.
It also uses the dot tool provided by the graphviz software to generate graphs.

Install Graphviz
****************
1. Install Graphviz

On Windows, installing Graphviz library is done differently. Check out the
`Graphviz downloads page <https://graphviz.org/download/>`_. Be sure that the ``graphviz/bin``
directory is in the ``PATH`` environment variable (there's an option in the installer for this).
After Graphviz is installed, reboot the PC so the updated ``PATH`` environment variable takes affect.
.. code-block:: shell

On Linux, just run:
sudo apt-get install graphviz

.. code-block:: shell
2. Installing Sphinx necessities

sudo apt-get install graphviz

Installing Sphinx necessities
*****************************

.. note::
If you installed sphinx using ``apt``, then it is likely out-of-date and will override any virtual
python environments installation of Sphinx. Simply uninstall sphinx (using ``apt``) will remedy
this problem.
.. note::
If you installed sphinx using ``apt``, then it is likely out-of-date and will override any virtual
python environments installation of Sphinx. Simply uninstall sphinx (using ``apt``) will remedy
this problem.

.. code-block:: bash
.. code-block:: bash

python -m pip install -r docs/requirements.txt
python -m pip install -r docs/requirements.txt

.. important::
If pip outputs a warning about your ``path/to/Python/Python3x/Scripts`` folder not
added to your OS environment variable ``PATH``, then you will likely get an error message like
``sphinx-build command not found`` when building the documentation. For more information on
installing sphinx, see the
`official Sphinx install instructions
<https://www.sphinx-doc.org/en/master/usage/installation.html>`_.
.. important::
If pip outputs a warning about your ``path/to/Python/Python3x/Scripts`` folder not
added to your OS environment variable ``PATH``, then you will likely get an error message like
``sphinx-build command not found`` when building the documentation. For more information on
installing sphinx, see the
`official Sphinx install instructions
<https://www.sphinx-doc.org/en/master/usage/installation.html>`_.

.. warning::
This documentation's theme requires Sphinx v4.0+. So, it is not recommended to install
sphinx from ``apt`` on Linux because the version distributed with the OS's PPA repository
may not be the most recent version of Sphinx.
.. warning::
This documentation's theme requires Sphinx v4.0+. So, it is not recommended to install
sphinx from ``apt`` on Linux because the version distributed with the OS's PPA repository
may not be the most recent version of Sphinx.

Building the Documentation
--------------------------
3. Building the Documentation

To build the documentation locally, the pyrf24 package needs to be installed first. Then run:
To build the documentation locally, the pyrf24 package needs to be installed first. Then run:

.. code-block:: bash
.. code-block:: bash

cd docs
sphinx-build -E -W . _build
cd docs
sphinx-build -E -W . _build

The ``docs/_build`` folder should now contain the html files that would be hosted on deployment.
Direct your internet browser to the html files in this folder to make sure your changes have been
rendered correctly.
The ``docs/_build`` folder should now contain the html files that would be hosted on deployment.
Direct your internet browser to the html files in this folder to make sure your changes have been
rendered correctly.

.. note::
The flags ``-E`` and ``-W`` will ensure the docs fail to build on any error or warning
(just like it does when deploying the docs online).
.. note::
The flags ``-E`` and ``-W`` will ensure the docs fail to build on any error or warning
(just like it does when deploying the docs online).
5 changes: 5 additions & 0 deletions docs/index.rst
Original file line number Diff line number Diff line change
@@ -1,13 +1,17 @@
.. include:: ../README.rst

.. toctree::
:hidden:

self

.. toctree::
:hidden:

examples

.. toctree::
:hidden:
:caption: API Reference

rf24_api
@@ -16,6 +20,7 @@
rf24_mesh_api

.. toctree::
:hidden:

topology