search

iqm-finland / KQCircuits

KLayout Python library for integrated quantum circuit design.
GNU General Public License v3.0
134 stars 72 forks source link

Broken `Edit on Github` link for API pages of KQC documentation #92

Closed qpavsmi closed 4 months ago

qpavsmi commented 5 months ago

What happened? What you expected to happen?

I open an API page of KQC class, for example https://iqm-finland.github.io/KQCircuits/api/kqcircuits.elements.smooth_capacitor.html

I click the Edit on Github link and it attempts to redirect me to https://github.com/iqm-finland/KQCircuits/blob/main/docs/api/kqcircuits.elements.smooth_capacitor.rst, which does not exist. This happens for any page under the API documentation section.

Reason is that we configured sphinx to generate docs for all KQC classes and modules. These pages are autogenerated, and don't have a documentation "source" the same way hand-written documentation pages have.

KQC documentation generation should be reconfigured so that for API pages it doesn't show the Edit on Github link. This post should help to get started: https://github.com/sphinx-doc/sphinx/issues/2386#issuecomment-478403897

Versions

Version independent

Issue Severity

Low: it is annoying

Generating docs

You need to have KQCircuits installed as standalone and make sure docs (doc-requirements.txt) dependency extension is included. Then follow the guide here, but in summary:

cd docs
make html

The main page of docs will be generated at KQCircuits/docs/index.html

Definition of done

When browsing pages in the API documentation section, there shouldn't be a Edit on Github link that leads me to an error page.

f-martini commented 4 months ago

Hi! I would like to try to solve this issue as part of unitaryHACK 2024.

qpavsmi commented 4 months ago

Thanks! Feel free to post here or use unitaryhack discord #kqcircuits channel if you need additional support!

f-martini commented 4 months ago

Thanks! Feel free to post here or use unitaryhack discord #kqcircuits channel if you need additional support!

Thanks to the link you provided above, I was able to solve the issue. I've submitted a QM Individual Contributor License Agreement as specified in the guidelines, is there anything else I need to do to send a pull request? (currently I'm working on a fork of the project). Also, is there any template I can use to properly submit the pull request? Thanks in advance! :)

qpavsmi commented 4 months ago

You can submit the pull request even now if you want. The cla-bot only prevents the pull request from merging, but before that I still need to review the changes. We don't have a template, just push your branch and make a pull request out of it.