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

Automate protocols' docs #1007

Open
alecandido opened this issue Oct 11, 2024 · 0 comments
Open

Automate protocols' docs #1007

alecandido opened this issue Oct 11, 2024 · 0 comments
Labels
documentation Improvements or additions to documentation

Comments

@alecandido
Copy link
Member

A "Protocols" section in the docs already exists:
https://github.com/qiboteam/qibocal/blob/main/doc/source/protocols/index.rst

But it's completely written manually, and independent of the state of qibocal.protocols.

It may be nice to autogenerate some pages, including the index, based on the package content.
Essentially, we may add to the Routine object some labels (metadata), that help to categorize them, and link to the manually written pages.

E.g. the index at https://github.com/qiboteam/qibocal/blob/main/doc/source/protocols/index.rst may be based on category names, collected through a scan of the content of qibocal.package.
The unlabeled routines may inherit an "Others" label, such that they all fall in a single category, whose page may be automatically generated as well, just listing the interface of all the routines in the category (possibly exposing even the module/class docstring somewhere).

In principle, we could autogenerate all the pages, just writing the content in the modules. However, I personally don't like too much mixing the users' documentation with the source content (though there are plenty of popular packages doing it), so I'd rather keep the current protocols' guides where they are, and just autogenerate the interface for those who don't have a manually crafted page.

@alecandido alecandido added the documentation Improvements or additions to documentation label Oct 11, 2024
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

No branches or pull requests

1 participant