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

Docs: Addition of docs inventory (objects.inv) #5125

Open
1 task done
JP-Ellis opened this issue Sep 5, 2024 · 4 comments · May be fixed by #5131
Open
1 task done

Docs: Addition of docs inventory (objects.inv) #5125

JP-Ellis opened this issue Sep 5, 2024 · 4 comments · May be fixed by #5131
Assignees
@leandrodamascena
Labels
documentation Improvements or additions to documentation help wanted Could use a second pair of eyes/hands

Comments

@JP-Ellis
Copy link

JP-Ellis commented Sep 5, 2024

What were you searching in the docs?

I am documenting a repository which uses AWS Powertools for Lambda, using MkDocs. In general, it is possible to import inventories of other packages so that when the documentation is generated, links can go out to the relevant docs sites.

Examples include:

  • https://docs.aiohttp.org/en/stable/objects.inv
  • https://docs.pydantic.dev/latest/objects.inv
  • https://docs.python.org/3/objects.inv

It would appear that the AWS Powertools for Lambda documentation does not generate/include the inventory file

Is this related to an existing documentation section?

No response

How can we improve?

By ensuring that the file is available at its standard location (e.g. https://docs.powertools.aws.dev/lambda/python/latest/object.inv), or to document where it is being published.

Got a suggestion in mind?

No response

Acknowledgment

  • I understand the final update might be different from my proposed suggestion, or refused.
@JP-Ellis JP-Ellis added documentation Improvements or additions to documentation triage Pending triage from maintainers labels Sep 5, 2024
@boring-cyborg boring-cyborg
Copy link

boring-cyborg bot commented Sep 5, 2024

Thanks for opening your first issue here! We'll come back to you as soon as we can.
In the meantime, check out the #python channel on our Powertools for AWS Lambda Discord: Invite link

@leandrodamascena
Copy link
Contributor

Hi @JP-Ellis! Thanks for letting us know this exists, I had no idea about it and it looks like a great feature.

I'm trying to see how mkdocs implement this and how we can use this in Powertools. If you have any ideas and can share, I would really appreciate it.

@leandrodamascena leandrodamascena self-assigned this Sep 5, 2024
@leandrodamascena leandrodamascena removed the triage Pending triage from maintainers label Sep 5, 2024
@leandrodamascena leandrodamascena moved this from Triage to Backlog in Powertools for AWS Lambda (Python) Sep 5, 2024
@JP-Ellis
Copy link
Author

JP-Ellis commented Sep 5, 2024

MkDocs on its own is just for displaying Markdown files, but the mkdocstrings plugin is really useful to parse and convert the docstrings from the Python code into documentation and (importantly) an inventory file.

I'll see about making a little PoC over the weekend 🙂

@leandrodamascena
Copy link
Contributor

MkDocs on its own is just for displaying Markdown files, but the mkdocstrings plugin is really useful to parse and convert the docstrings from the Python code into documentation and (importantly) an inventory file.

I'll see about making a little PoC over the weekend 🙂

Ohh, great! We're trying to use mkdocstrings to create new documentation for the Parser and Event Source Data Classes, but it looks like we need a major refactoring in some parts of the documentation.

Please let me know if you need help with this PoC, we're very interested in adopting mkdocstrings.

@leandrodamascena leandrodamascena added the help wanted Could use a second pair of eyes/hands label Sep 5, 2024
JP-Ellis added a commit to JP-Ellis/powertools-lambda-python that referenced this issue Sep 5, 2024
@JP-Ellis
feat(docs): generate docs from docstrings
496379b 
This is a fairly major change to the docs and generates documentation for all
public methods, attributes and variables in AWS Powertools.

This is achieved using `mkdocstrings`, which replaces instances of

```markdown
::: some.module.path
```

with the documentation of the specified module.

As a side effect of generating the documentation, an `objects.inv` file is also
generated.

From a quick purview of the generated docs, they seem pretty good as the
underlying code appears well documented; however, this probably needs to be
double checked. Especially for cases where the Numpy docstring style is not
being followed which may result in errors generating the docs.

Ref: aws-powertools#5125
Signed-off-by: JP-Ellis <[email protected]>
@JP-Ellis JP-Ellis linked a pull request Sep 5, 2024 that will close this issue
Open
5 tasks
@leandrodamascena leandrodamascena linked a pull request Sep 9, 2024 that will close this issue
feat(docs): generate docs from docstrings #5131
Open
5 tasks
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Assignees

@leandrodamascena leandrodamascena

Labels
documentation Improvements or additions to documentation help wanted Could use a second pair of eyes/hands
Projects
Powertools for AWS Lambda (Python)
Status: Ideas
Milestone
No milestone
Development

Successfully merging a pull request may close this issue.

feat(docs): generate docs from docstrings JP-Ellis/powertools-lambda-python
2 participants
@JP-Ellis @leandrodamascena