Documentation
******************

Overview of how we use sphinx documentation in alchemy.


Installation
=================


Setting up Pycharm for writing Docstrings
=================

You want Pycharm to be using restructured text for the docstrings.  This is done by going to:\

```
Pycharm -> Preferences -> Tools -> Python Integrated Tools -> Docstrings
```
and setting the docstring format to reStructuredText.

You're also going to want to be using github copilot for your docstrings.

I personally use this methodology when writing code with copilot:
1) Write my own docstrings to give it a hint of what I want
2) Use copilot to fill out the code
3) Delete my docstrings and use copilot to write the docstrings for me perfectly formatted.

This is by far the cleanest/easiest way to write them.


Previewing Docstrings locally
=================

It's easier than you think to do this locally.  If you're working in alchemy all the needed
python packages are already installed.  You just need to run the following command in the docs folder
in the pycharm terminal:

```
make clean
make html
```
If you've added new files you'll need to run the following command to update the modules folder with rst files for each new module.

```
sphinx-apidoc [OPTIONS] -o <OUTPUT_PATH> <MODULE_PATH> [EXCLUDE_PATTERN …]
```

which if you're in the docs folder in the terminal turns out like this

```
sphinx-apidoc -o ./modules ../cgl
```

this will generate rst files for all the files in the cgl folder.

They'll now show up in the search and in the modules section of the docs.

If you want to call special attention to your python files and their doc strings
follow what we've done in the table of contents in the index.rst file.