Maintaining
============

Updating and Deploying Documentation
--------------------------------------

To create a fully-functional fork of the repository in your Github, `set up a Github Pages project`_ for the new repository. When setting it up, associate the page with the `master` branch. The documentation will now be available publicly.

Edit the files in the ``sphinx/`` directory how you see fit. Documentation for individual classes and files might be found in the source, since documentation is partially autogenerated from comments in the actual code.

The documentation must then be generated. Change directories to the ``sphinx/`` folder, then run ``make github``. This will build the html web files for the online documentation and place them in the ``docs/`` folder. Add the files in the ``docs/`` and ``sphinx/`` in a new commit and push to master. The changes will be reflected on your project Github page.

Creating a Release
-------------------

It's important to run the unit tests for the package before pushing a full release:

.. code-block:: bash

   python3 ally/tests.py

To create a release, make sure to change the version number in 4 different files:

* ``README.md``
* ``sphinx/index.rst``
* ``sphinx/conf.py``
* ``setup.py``

Once this is done, all the documentation pages will reflect the new version, and the package release will respect this as well.

Make sure to add new contributers to the ``sphinx/index.rst`` and ``README.md`` pages, if applicable.

To build the package and upload to Pypi, run the commands from the root directory:

.. code-block:: bash

   python3 setup.py sdist bdist_wheel
   twine upload dist/*

The code will now be reflected in Pypi, available for public use.

.. _`set up a Github Pages project`: https://docs.github.com/en/github/working-with-github-pages/creating-a-github-pages-site