search

arup-group / genet

Manipulate MATSim networks via a Python API.
MIT License
44 stars 9 forks source link

Add github pages configuration and some basic docs pages #229

Closed brynpickering closed 8 months ago

brynpickering commented 8 months ago

Move to github pages for the docs.

This will render all the example notebooks and display them, so none of that information is lost from the wiki.

I've also moved most of the installation instructions to the docs and given use of Docker its own page.

I got about 60% of the way through updating the docstrings, but it is mind-numbing stuff so I focussed on the most important classes. I also updated type hinting as I was going along.

Why update docstrings? If docstrings are set up correctly then when rendering the docs, it will pick up on inconsistencies between the function signature and the docstrings, so you can catch issues where you've updated your function sig but not your docstring. Also, I see lots of complaints from mypy now that I've updated type hinting enough for it to kick in (it tends not to bother if you haven't put in enough hints).

So 99.9% the changes to the source code in this PR are just to docstrings and type hints. I did also move around some abstract methods of ScheduleElements and made it an actual abstract class (until now @abstractmethod decorator wasn't doing anything), but tests still pass locally so I'm hoping that hasn't broken anything ;)

codecov-commenter commented 8 months ago

Codecov Report

All modified and coverable lines are covered by tests :white_check_mark:

Comparison is base (e2f38cd) 92.08% compared to head (49ab9f6) 92.19%.

Additional details and impacted files ```diff @@ Coverage Diff @@ ## main #229 +/- ## ========================================== + Coverage 92.08% 92.19% +0.10% ========================================== Files 37 37 Lines 6620 6623 +3 Branches 1588 1590 +2 ========================================== + Hits 6096 6106 +10 + Misses 305 298 -7 Partials 219 219 ```

:umbrella: View full report in Codecov by Sentry.
:loudspeaker: Have feedback on the report? Share it here.

brynpickering commented 8 months ago

mostly around rendering the docs - I don't know if I'm jumping the gun and some magic will happen to them after this branch is merged to master??

Yeah, it's a bit annoying that we can't use readthedocs for our documentation, as that would create a test version of the docs in every Pull Request. Then you could browse the pages as they will be rendered. As it is, to review the docs you need to render them locally (quickest: mkdocs serve).