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.

Sign up for GitHub

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

Jump to bottom

Add API documentation generation and use Markdown #160

Merged
merged 5 commits into from
Nov 10, 2024
Merged

Add API documentation generation and use Markdown #160

merged 5 commits into from
Nov 10, 2024

Conversation

b0661
Copy link
Collaborator

@b0661 b0661 commented Oct 10, 2024 •
edited
Loading

Add generation of the API documentation for akkudoktoreos and akkudoktoreosserver packages.

  • The API documentation is generated by the Sphinx autosummary and autodoc extensions. The autodoc extension extracts the API info from the Sphinx type docstrings or Google type docstrings of the Python packages.
  • The API documentation is also checked by ruff rules. Docstrings are currently not enforced to keep the current code base without change. Minor documentation quirks were adapted to the ruff rules.

Add documentation generation for the server interface

Move most of the documentation to Markdown format

Documentation generation emits some warnings that I could not solve. This does not prevent the creation of the API doc.

You may have a look in the documentation by:

make read-docs

@b0661 b0661 force-pushed the pr_doc_api branch 2 times, most recently from ebc0238 to c9ac4a8 Compare October 10, 2024 18:03
@drbacke
Copy link
Collaborator

drbacke commented Oct 11, 2024

@b0661 Please resolve the conflicts. Then I will merge it directly. Very helpfull

@b0661
Copy link
Collaborator Author

b0661 commented Oct 11, 2024 •
edited
Loading

@drbacke Conflicts resolved.

@b0661 b0661 force-pushed the pr_doc_api branch 2 times, most recently from 48295c9 to c604117 Compare October 12, 2024 08:07
@b0661 b0661 mentioned this pull request Oct 19, 2024
Closed
@drbacke drbacke marked this pull request as draft October 22, 2024 08:47
@drbacke
Copy link
Collaborator

drbacke commented Oct 22, 2024

Please re-run all tests, code changed quite a lot

b0661 added 3 commits October 22, 2024 16:22
@b0661
Add package API documentation generation
0bdd06c 
Add generation of the API documentation for akkudoktoreos
and akkudoktoreosserver packages.

The API documentation is generated by the Sphinx autosummary extension.

Signed-off-by: Bobby Noelte <[email protected]>
@b0661
Enable Google style source commenting and documentation generation.
e1a8660 
Enable automatic documentation generation from Google style docstrings in the source.

Signed-off-by: Bobby Noelte <[email protected]>
@b0661
Check Google style source commenting.
b9790ba 
Check Google style commenting by the appropriate ruff rules.

Commenting is _NOT_ enforced. Missing docstrings are ignored.

Minor commenting quirks of the code base are adapted.

Signed-off-by: Bobby Noelte <[email protected]>
@b0661 b0661 marked this pull request as ready for review October 22, 2024 14:36
@b0661
Copy link
Collaborator Author

b0661 commented Oct 22, 2024

Please re-run all tests, code changed quite a lot

@drbacke, tests passed.

@b0661 b0661 mentioned this pull request Oct 24, 2024
Closed
@b0661
Improve Markdown handling and switch to Markdown documentation.
b265fed 
Switch to Markdown for the documentation files to improve the user and developer experience (see issue Akkudoktor-EOS#181).

Keep files with special directives for automatic API documentation in RST format. The
directives expect RST.

Also add dummy handling for openai/ swagger server documentation. The openai interface definition is
for now taken from the fastapi PR as EOS will switch to fastAPI.

Signed-off-by: Bobby Noelte <[email protected]>
@b0661 b0661 changed the title Add package API documentation generation Add API documentation generation and use Markdown Oct 25, 2024
@NormannK NormannK merged commit 6561793 into Akkudoktor-EOS:main Nov 10, 2024
2 checks passed
@b0661 b0661 deleted the pr_doc_api branch November 12, 2024 03:43
drbacke pushed a commit that referenced this pull request Jan 1, 2025
@b0661 @NormannK
Add API documentation generation and use Markdown (#160)
6a65f84 
* Add package API documentation generation

Add generation of the API documentation for akkudoktoreos
and akkudoktoreosserver packages.

The API documentation is generated by the Sphinx autosummary extension.

Signed-off-by: Bobby Noelte <[email protected]>

* Enable Google style source commenting and documentation generation.

Enable automatic documentation generation from Google style docstrings in the source.

Signed-off-by: Bobby Noelte <[email protected]>

* Check Google style source commenting.

Check Google style commenting by the appropriate ruff rules.

Commenting is _NOT_ enforced. Missing docstrings are ignored.

Minor commenting quirks of the code base are adapted.

Signed-off-by: Bobby Noelte <[email protected]>

* Improve Markdown handling and switch to Markdown documentation.

Switch to Markdown for the documentation files to improve the user and developer experience (see issue #181).

Keep files with special directives for automatic API documentation in RST format. The
directives expect RST.

Also add dummy handling for openai/ swagger server documentation. The openai interface definition is
for now taken from the fastapi PR as EOS will switch to fastAPI.

Signed-off-by: Bobby Noelte <[email protected]>

---------

Signed-off-by: Bobby Noelte <[email protected]>
Co-authored-by: Normann <[email protected]>
Lasall pushed a commit that referenced this pull request Jan 1, 2025
@b0661 @NormannK
Add API documentation generation and use Markdown (#160)
ccf44ba 
* Add package API documentation generation

Add generation of the API documentation for akkudoktoreos
and akkudoktoreosserver packages.

The API documentation is generated by the Sphinx autosummary extension.

Signed-off-by: Bobby Noelte <[email protected]>

* Enable Google style source commenting and documentation generation.

Enable automatic documentation generation from Google style docstrings in the source.

Signed-off-by: Bobby Noelte <[email protected]>

* Check Google style source commenting.

Check Google style commenting by the appropriate ruff rules.

Commenting is _NOT_ enforced. Missing docstrings are ignored.

Minor commenting quirks of the code base are adapted.

Signed-off-by: Bobby Noelte <[email protected]>

* Improve Markdown handling and switch to Markdown documentation.

Switch to Markdown for the documentation files to improve the user and developer experience (see issue #181).

Keep files with special directives for automatic API documentation in RST format. The
directives expect RST.

Also add dummy handling for openai/ swagger server documentation. The openai interface definition is
for now taken from the fastapi PR as EOS will switch to fastAPI.

Signed-off-by: Bobby Noelte <[email protected]>

---------

Signed-off-by: Bobby Noelte <[email protected]>
Co-authored-by: Normann <[email protected]>
Lasall pushed a commit that referenced this pull request Jan 1, 2025
@b0661 @NormannK
Add API documentation generation and use Markdown (#160)
94467e1 
* Add package API documentation generation

Add generation of the API documentation for akkudoktoreos
and akkudoktoreosserver packages.

The API documentation is generated by the Sphinx autosummary extension.

Signed-off-by: Bobby Noelte <[email protected]>

* Enable Google style source commenting and documentation generation.

Enable automatic documentation generation from Google style docstrings in the source.

Signed-off-by: Bobby Noelte <[email protected]>

* Check Google style source commenting.

Check Google style commenting by the appropriate ruff rules.

Commenting is _NOT_ enforced. Missing docstrings are ignored.

Minor commenting quirks of the code base are adapted.

Signed-off-by: Bobby Noelte <[email protected]>

* Improve Markdown handling and switch to Markdown documentation.

Switch to Markdown for the documentation files to improve the user and developer experience (see issue #181).

Keep files with special directives for automatic API documentation in RST format. The
directives expect RST.

Also add dummy handling for openai/ swagger server documentation. The openai interface definition is
for now taken from the fastapi PR as EOS will switch to fastAPI.

Signed-off-by: Bobby Noelte <[email protected]>

---------

Signed-off-by: Bobby Noelte <[email protected]>
Co-authored-by: Normann <[email protected]>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Reviewers

@michaelosthege michaelosthege michaelosthege left review comments

Assignees
No one assigned
Labels
None yet
Projects
None yet
Milestone
No milestone
Development

Successfully merging this pull request may close these issues.
4 participants
@b0661 @drbacke @michaelosthege @NormannK