andrewtavis / andrewtavis/poli-sci-kit
Add equations to appointment.metrics docstrings
- Dominant language
- Python
- Stars
- 34
- Forks
- 8
- PR merge metrics
- No merged PRs in 30d
Description
This issue is for adding LaTeX equations to the docstrings of all functions found in [poli_sci_kit.appointment.metrics](https://github.com/andrewtavis/poli-sci-kit/blob/main/src/poli_sci_kit/appointment/metrics.py). The style should be similar to those found in [poli_sci_kit.appointment.methods](https://github.com/andrewtavis/poli-sci-kit/blob/main/src/poli_sci_kit/appointment/methods.py).
The following is an explanation for how to write LaTeX in docstrings:
1. In [conf.py](https://github.com/andrewtavis/poli-sci-kit/blob/main/docs/source/conf.py) of the documentation you need the extension `sphinx.ext.imgmath`, which allows equations to be rendered to pngs (this has been added to poli-sci-kit's `conf.py`)
2. If you want to add an equation, then as seen in the docstrings for [appointment.methods](https://github.com/andrewtavis/poli-sci-kit/blob/main/src/poli_sci_kit/appointment/methods.py) you add the following:
```
.. math::
LaTeX you want rendered
```
3. The docstring also needs to be converted to an [r-sting](https://stackoverflow.com/questions/2081640/what-exactly-do-u-and-r-string-flags-do-and-what-are-raw-string-literals) (this is now the case for `largest_remainder` and `highest_averages`)
4. You also need to use `&=` instead of `=` in equations
This [LaTeX editor](https://latex.codecogs.com/eqneditor/editor.php) could be used to test equations and then add them to the docstrings (remembering `&=` instead of `=`). I would be more than happy to help if one of the equations doesn't make sense, or if getting the LaTeX to work is a bit confusing :)
Thanks for your interest in contributing!
Contributor guide
Research direction
Start with src/poli_sci_kit/appointment/metrics.py and compare its function docstrings with src/poli_sci_kit/appointment/methods.py. Check docs/source/conf.py for the existing imgmath extension, then add rendered LaTeX equations to every metrics docstring using raw strings and \\&=. Done means all functions have equations that follow the established style and render correctly in the documentation.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- latex, python
- Domain
- documentation
- Issue type
- Documentation
- Difficulty
- 3/5
- Estimated time
- 1-2 days
- Activity status
- Stale
- Clarity
- Clearly specified
- Newbie friendliness
- 55/100