Docs: Addition of docs inventory (objects.inv)

[JP-Ellis]

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.

[boring-cyborg]

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]

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.

[JP-Ellis]

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]

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.

[dreamorosi]

We're working on replacing pdoc3 with mkdocstrings which should handle the creation of the objects.inv file automatically.

You can track status here #4632. We'll also report back here once we're done.

[leandrodamascena]

We've successfully migrated our API documentation to mkdocstrings. While we might need to fine-tune things based on customer feedback in the future, we're now exposing almost all public components. Compared to pdoc3, this new plugin is significantly more user-friendly and I really liked it.

The new documentation and inventory will be published on our next release, what is expected for 11/02.

Closing this issue as complete.

[github-actions]

⚠️COMMENT VISIBILITY WARNING⚠️

This issue is now closed. Please be mindful that future comments are hard for our team to see.

If you need more assistance, please either tag a team member or open a new issue that references this one.

If you wish to keep having a conversation with other community members under this issue feel free to do so.