Create sphinx doc

[jo-mueller]

Description

• I added (automatically generated) basic documentation of all modules, functions and example notebooks. I created a workflow that automatically rebuilds the doc pages upon PR requests. The documentation can always be created manually during development by running make html inside the docs file.

• I furthermore moved the example notebooks to docs/_include/notebooks to make them available to the html build.

• I made minor changes in practically every docstring to make them consistent with numpy format standards.

• I added the link to the documentation page to the front-page Readme.

Type of change

• Bug-fix
• New feature
• Breaking change
• Documentation update

References

Addresses #25

Tests

• I adapted existing tests, because
• I added new tests to cover the code change
• All tests pass with my change

Final checks

• My change is the minimal possible work for the desired feature/fix
• I updated the documentation where necessary to cover the change

[jo-mueller]

Sidenote on the many commits: I tried to implement a github action that would automatically build the documentation as soon as a PR is submitted but this does not seem to work nicely. Deploying the html pages to biapol.github.io/biapol-utilities works well, though.

This means, that every future PR with a new function would have to be preceded by a call of make html in the docs file. Is this feasible?

[haesleinhuepf]

This means, that every future PR with a new function would have to be preceded by a call of make html in the docs file. Is this feasible?

It should be possible with git at every commit. But for now I would maybe invoke this manually, and add a checkbox to the PR-template to remind us ;-)

Btw. this cannot be reviewed efficiently as 105 files have been changed. Thus, I suggest you merge and cross fingers that nothing breaks ;-)

[jo-mueller]

Btw. this cannot be reviewed efficiently as 105 files have been changed. Thus, I suggest you merge and cross fingers that nothing breaks ;-)

Yes, this is indeed a problem, which will persist on future PRs, as updating the doc will create a lot of downstream file changes (html build, etc). Another solution (which is apparently often used) is to push the generated doc files to a separate branch that hosts the documentation.

[haesleinhuepf]

@jo-mueller Please add a section "How to build documentation" to the readme. Afterwards, feel freel to merge. Check if everything still works then.

[jo-mueller]

Sorry for the back and forth on this topic. I am trying to get a workflow running that automatically builds the doc and pushes it to a separate branch but can't really get it to work. 🙄

[jo-mueller]

Sorry for the back and forth on this topic. I am trying to get a workflow running that automatically builds the doc and pushes it to a separate branch but can't really get it to work. 🙄

Maybe that's a topic for a new PR :)