Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Generate docs #21

Closed
sco1 opened this issue Aug 2, 2024 · 3 comments · Fixed by #31
Closed

Generate docs #21

sco1 opened this issue Aug 2, 2024 · 3 comments · Fixed by #31
Labels
documentation Improvements or additions to documentation
Milestone

Comments

@sco1
Copy link
Owner

sco1 commented Aug 2, 2024

The README is already getting a bit long, it's probably worth investigating generating some static docs. Can probably use GH Pages?

pdoc3 looks like it could fit the bill.

Rather use pdoc instead.

@sco1 sco1 added the documentation Improvements or additions to documentation label Aug 2, 2024
@sco1
Copy link
Owner Author

sco1 commented Aug 2, 2024

5fc37f7 adds a simple pdoc workflow & deploys to GH Pages on pushes to main. Some tweaks should still be made before explicitly pointing to it but it's a good starting point.

@sco1
Copy link
Owner Author

sco1 commented Aug 7, 2024

CLI documentation needs some looking at. While the function documentation is being correctly pulled, because Typer is providing the command grouping the CLI structure is not captured by pdoc so the documentation does not make clear what each function belongs to.

It would also be helpful to figure out how to incorporate some of the other markdown documents as their own pages, e.g. the README, contributing doc, and data model doc.

@sco1 sco1 added this to the v1.0 milestone Aug 20, 2024
@sco1
Copy link
Owner Author

sco1 commented Aug 21, 2024

As much as I like having the pdoc one-liner, it might be better in the long run to do something more like https://github.com/mkdocs/mkdocs + https://github.com/mkdocstrings/mkdocstrings to allow for better customizability, particularly around the CLI documentation where pdoc has a tough time following along with typer's structure

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
documentation Improvements or additions to documentation
Projects
None yet
Development

Successfully merging a pull request may close this issue.

1 participant