=================================
Writing documentation for amstrax
=================================

Keeping amstrax documented benifits new users as well as exciting.

First of all, information can be changed in ``amstrax/doc``. For example
this page is  ``amstrax/doc/writing_documentation.rst``. New pages can
be included in  ``amstrax/doc``. If you add a new file here, don't forget
to include it in ``amstrax/doc/index.rst`` (without the .rst, see the
existing pages there).

Datastructure pages
___________________
In the documentation, arguably the most usefull pages are the pages of
the plugin datastructure.
These pages are autogenerated in ``amstrax/docs/build_data_structure_doc.py``.
If you want to add a new context there, you will have to add it in the
``build_data_structure_doc`` function. Also don't forget to add it to
``amstrax/doc/index.rst``.

Testing changes to documentation and debugging
----------------------------------------------
Sometimes the documentation will break and you need to test why it's not
working anymore.

To do this go to ``amstrax/docs`` and do ``bash make_docs.sh``. Hopefully
this will get you started with debugging.

You might need to install a few dependencies but this is outside of the
scope of this page. Just do a few conda/pip installs and hope for the best.

If you want to see the output of your build, navigate to
``amstrax/docs/build/html`` and open one of the ``.html`` files.