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

Prepare Contributor guides to be readable directly in GitHub #290

Closed
Eric-Arellano opened this issue Nov 6, 2023 · 2 comments
Closed

Prepare Contributor guides to be readable directly in GitHub #290

Eric-Arellano opened this issue Nov 6, 2023 · 2 comments

Comments

@Eric-Arellano
Copy link
Collaborator

Eric-Arellano commented Nov 6, 2023

Per #24 (comment), we are proposing for these 3 files to solely live as Markdown files simply live in the Qiskit repo, rather than being in the docs. That complies with normal open source expectations.

https://github.com/Qiskit/qiskit/blob/main/docs/maintainers_guide.rst
https://github.com/Qiskit/qiskit/blob/main/docs/deprecation_policy.rst
https://github.com/Qiskit/qiskit/blob/main/docs/contributing_to_qiskit.rst

Still, we need to convert them from RST to MD (not MDX) so that they render more usefully in GitHub rich preview. We can use Myst's converter: https://rst-to-myst.readthedocs.io/en/latest/cli.html#rst2myst-convert, but we need to check if there are any Sphinx-isms.

It's fine if we keep the files in RST, or we could also rewrite to Markdown. The important thing is that the rich preview in GitHub can render everything. Right now we have some Sphinx-isms like :ref:.

@Eric-Arellano Eric-Arellano added this to the 23-11-29 dec release milestone Nov 6, 2023
@Eric-Arellano Eric-Arellano changed the title Convert Contributor Guide out of RST Prepare Contributor guides to be readable directly in GitHub Nov 8, 2023
@Eric-Arellano
Copy link
Collaborator Author

@javabster fyi I updated this with the realization it doesn't matter if we rewrite to Markdown. It's fine to stick with RST. The important thing is removing Sphinx-isms like :ref: that don't render well in GitHub's rich preview.

@Eric-Arellano
Copy link
Collaborator Author

@javabster thanks for opening Qiskit/qiskit#11218 and Qiskit/qiskit#11217!!

Where will we point to these markdown guides from in the quantum.ibm.com docs, if it all? I think it'd probably be good to have a small Conributing part of our docs that simply links out to these new guides.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Projects
Archived in project
Development

No branches or pull requests

2 participants