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

docs: Generate documentation with sphinx #121

Merged
merged 8 commits into from
Dec 23, 2024
Merged

docs: Generate documentation with sphinx #121

merged 8 commits into from
Dec 23, 2024

Conversation

Melkor333
Copy link
Contributor

@Melkor333 Melkor333 commented Nov 11, 2024

I introduced sphinx docs and just used our Adfinis template (FWIW this can probably be replaced by plain sphinx+configuration at some point, see my PR and its discussion).
- Please download the latest artifact and take a look at it. I'm quite happy with how it looks right now (not perfect, but IMO good enough to be merged)

  • Added a docs task in the Makefile
    • Yes I manually install md-click because it's kinda abandoned. I'd love to revive it in the Adfinis Namespace, but if you devs don't have a use for it, let's just stick to the quick-fix for now.
  • usage docs with md-click. This generates multiple files which I merge to make it more convenient
    • I had to rename @cli.command to @pyaptly.command in cli.py to make the generated docs more comprehensible.
    • I merge the generated files and do some adjustment of the headers in the Makefile
  • code docs with Autodocs (not very useful but only took like 5 mins... :) )
  • A jsonschema of the configuration file at pyaptly/config.schema.json
    • I use it to generate the docs
    • I also added a validation function to the main.py which uses the jsonschema.
  • My linter did some things in publish.py and test_publish.py which I added in a separate commit

@Melkor333 Melkor333 self-assigned this Nov 11, 2024
@Melkor333 Melkor333 marked this pull request as draft November 11, 2024 07:58
@Melkor333
Copy link
Contributor Author

This should also close #113 when finished.

@Melkor333
Copy link
Contributor Author

Got internal feedback that maybe gitbook or vuebook might be a "more modern" approach than going back to sphinx... Since everything is markdown the only missing piece would be the pydocs which could probably be converted to md with something like pydoc-markdown

@Melkor333 Melkor333 force-pushed the new-docs branch 2 times, most recently from f825e62 to c42ae6b Compare December 19, 2024 09:59
@Melkor333 Melkor333 changed the title Draft: docs: Generate documentation with sphinx docs: Generate documentation with sphinx Dec 19, 2024
@Melkor333 Melkor333 requested a review from winged December 19, 2024 10:25
@Melkor333 Melkor333 marked this pull request as ready for review December 19, 2024 10:29
@fadnincx fadnincx marked this pull request as ready for review December 19, 2024 10:29
Copy link
Member

@winged winged left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Awesome work! I only have a little nitpick, otherwise LGTM!

pyaptly/main.py Outdated Show resolved Hide resolved
@Melkor333 Melkor333 merged commit d77954b into main Dec 23, 2024
2 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

Successfully merging this pull request may close these issues.

2 participants