Update contributing guide (#2382)

* update both guides * forgot readme * move things around * inline link cleanup * Nate's review - corrected typos Co-authored-by: nate stemen <[email protected]> * Apply suggestions from code review Co-authored-by: nate stemen <[email protected]> --------- Co-authored-by: nate stemen <[email protected]>
unitaryfund · Jun 12, 2024 · bf82e84 · bf82e84
1 parent 720079d
commit bf82e84
Show file tree

Hide file tree

Showing 2 changed files with 77 additions and 17 deletions.
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -5,7 +5,7 @@ The most common ways to contribute here are
 
 1. opening an [issue](https://github.com/unitaryfund/mitiq/issues/new) to report a bug or propose a new feature, or ask a question, and
 2. opening a [pull request](https://github.com/unitaryfund/mitiq/pulls) to fix a bug, or implement a desired feature.
-3. opening a [discussion post](https://github.com/unitaryfund/mitiq/discussions) to ask a question (no stupid questions!), provide feedback, or show something off!
+3. opening a [discussion post](https://github.com/unitaryfund/mitiq/discussions) to ask a question (all questions welcome!), provide feedback, or show something off!
 
 The rest of this document describes the technical details of getting set up to develop, and make your first contribution to Mitiq.
 
@@ -47,7 +47,7 @@ Once they pass, you can run the entire test suite (excluding those that require
 make test
 ```
 
-This can often be slow, however, so testing your changes iteratively using `pytest` is often faster when doing development.
+This can often be slow, however, so testing your changes [iteratively](https://docs.pytest.org/en/7.1.x/how-to/usage.html#specifying-which-tests-to-run) using `pytest` is often faster when doing development. 
 
 To run the tests for the pyQuil plugins, run
 ```bash
@@ -68,7 +68,7 @@ docker run --rm -idt -p 5555:5555 rigetti/quilc -R
 ```
 
 ### Updating the documentation
-Follow these [instructions for contributing to the documentation](https://mitiq.readthedocs.io/en/latest/contributing_docs.html) which include guidelines about updating the API-doc list of modules and writing examples in the users guide.
+Follow these [instructions for contributing to the documentation](contributing_docs.md) which include guidelines about updating the API-doc, adding examples, and updating the user guide.
 
 ### Style guidelines
 
@@ -116,14 +116,26 @@ This is a list of accepted request-for-comments (RFC) documents by date of creat
 - [Error Mitigation by Subspace Expansion](https://docs.google.com/document/d/1JyQAwiw8BRT_oucZ6tQv0id6UhSdd3df1mNSPpOvu1I) by Ammar Jahin, Dariel Mok , Preksha Naik, Abdulrahman Sahmoud (@bubakazouba) Apr 28, 2023
 - [Implementation RFC for Mitiq calibration](https://docs.google.com/document/d/1EZUJyEEUQUH33UOgSIzCCvXyxP0WLOQn11W0x4Ox4nY/edit) by Andrea Mari (@andreamari) Nov 2, 2022
 - [Calibration tools for error mitigation RFC (abstract general solutions)](https://docs.google.com/document/d/1otUHnTlyNS-0rxGAxltHLF1iD5C9qT9oEZ3jn8VHWgw/edit) by Andrea Mari (@andreamari) Oct 6, 2022
-- [Identity insersion scaling RFC](https://docs.google.com/document/d/1hbd9frjYiSy0WujA0iCccc-oMO4Q-kZc2G4b3lkJHdk/edit) by Purva Thakre (@purva-thakre) Jun 29, 2022
+- [Identity insertion scaling RFC](https://docs.google.com/document/d/1hbd9frjYiSy0WujA0iCccc-oMO4Q-kZc2G4b3lkJHdk/edit) by Purva Thakre (@purva-thakre) Jun 29, 2022
 - [Readout Confusion Inversion RFC](https://docs.google.com/document/d/1buO5PrO5sS02VXjcaYf37RuR0rF6xpyr4J9H1tI4vN4/edit) by Amir Ebrahimi (@amirebrahimi) Jun 16, 2022
 - [Documentation reorganization RFC](https://docs.google.com/document/d/13un5TZPknSOhmOBkrL2rsofjGfdp2jDnd-DywLpGFPc/edit) by Ryan LaRose (@rmlarose) Dec 1, 2021
 - [Learning-based PEC RFC](https://docs.google.com/document/d/1VItesy6R5SlUa_YXW1km7IjFZ8kzyFeHUepHak1fEh4/edit) by Misty Wahl (@Misty-W) Oct 25, 2021
 - [Digital dynamical decoupling RFC](https://docs.google.com/document/d/1cRwFCTn6kUjI1P0kNydtevxIYtE4r8Omd_iWK0Pe8qo/edit) by Aaron Robertson (@Aaron-Robertson) Jan 28, 2021
 
+### Checklist for adding an approved QEM Technique
+
+After your RFC is accepted, the proposed feature (for example, a new QEM Method) will require the following:
+
+- Add the new QEM method to `mitiq/abbreviated_name_of_qem_method` such that the corresponding units tests are in `mitiq/abbreviated_name_of_qem_method/tests`
+- The code must follow the formatting and style guidelines discussed [above](#style-guidelines),
+- The new module should be added to the [](apidoc.md) using the instructions found in [](contributing_docs.md#automatically-add-information-from-the-api-docs),
+- Add documentation for the new QEM method, additional details are available in [](contributing_docs.md#adding-files-to-the-user-guide),
+- Update `docs/source/guide/glossary.md` with a one-line summary of what your new feature accomplishes, and
+- Update the [](./readme.md#quick-tour) section of the `README.md` with information related to your new technique.
+
+
 ## Code of conduct
-Mitiq development abides to the [Contributors' Covenant](https://mitiq.readthedocs.io/en/latest/code_of_conduct.html).
+Mitiq development abides to the [](./code_of_conduct.md).
 
 ## Lifecycle
 The basic development workflow for Mitiq is done in units of milestones which are usually one month periods where we focus our efforts on thrusts decided by the development team, alongside community members.
@@ -132,5 +144,3 @@ Milestones are tracked using the [GitHub milestone feature](https://github.com/u
 All releases for Mitiq are tagged on the `main` branch with tags for the version number of the release.
 Find all the previous releases [here](https://github.com/unitaryfund/mitiq/releases).
 
-## Code of conduct
-Mitiq development abides to the [Contributors' Covenant](https://mitiq.readthedocs.io/en/latest/code_of_conduct.html).
diff --git a/docs/CONTRIBUTING_DOCS.md b/docs/CONTRIBUTING_DOCS.md
@@ -39,16 +39,14 @@ extensions = ['sphinx.ext.autodoc']
 
 Documentation is found in `docs/source`, and is divided into the following sections:
 
--  a **guide**, whose content needs to be
-written from scratch, 
-- **examples** which can be either jupyter notebooks or MyST formatted notebooks, and
-- an **API-doc** part, which is (mostly)
-automatically generated.
+-  a **guide**, whose content needs to be written from scratch for new features. For more details, go to [](contributing.md#proposing-a-new-feature-to-mitiq) and [](contributing_docs.md#adding-files-to-the-user-guide)
+- **examples** which can be either a jupyter notebook or a MyST formatted notebook. A checklist is available in [](contributing_docs.md#adding-example-files)
+- an **API-doc** part, which is (mostly) automatically generated. See [](contributing_docs.md#automatically-add-information-from-the-api-docs) for additional information.
 
 Information in the docs should be added as markdown files using the MyST markdown syntax.
 If you are adding a new file (as opposed to editing an existing one), ensure to add it to an associated TOC so that it is discoverable.
 
-The main table of contents (TOC) file for the docs is `index.md`. It includes `guide\guide.md` and `apidoc.md`, among other files. To add a new file to the base TOC, make sure it gets listed in the `toctree` directive like this:
+The main table of contents (TOC) file for the docs is `index.md`. It includes `guide/guide.md` and `apidoc.md`, among other files. To add a new file to the base TOC, make sure it gets listed in the `toctree` directive like this:
 ````
 ```{toctree}
 ---
@@ -76,12 +74,56 @@ To include `.md` files outside of the documentation `source` directory, you can
 
 where `file.md` is the one to be added. For more information on including files external to the docs, see the [MyST docs](https://myst-parser.readthedocs.io/en/latest/).
 
+
+
 ### Adding files to the user guide
 
 To add information in the guide, please add markdown (`.md`) files to the `docs/guide` directory.
 Remember to add new files to the guide's TOC file `docs/source/guide/guide.md`.
 
-### Adding workflow images to the user guide
+#### User Guide Outline
+
+The different sections of a User's guide comprises of:
+
+- How do I use `new_QEM_method` labeled as `new_QEM_method-1-intro.md`?
+- When should I use `new_QEM_method` labeled as `new_QEM_method-2-use-case.md`?
+- What additional options are available in `new_QEM_method` labeled as `new_QEM_method-3-options.md`?
+- What happens when I use `new_QEM_method` labeled as `new_QEM_method-4-low-level.md`?
+- What is the theory behind `new_QEM_method` labeled as `new_QEM_method-5-theory.md`?
+
+The main landing page will link all the sections of the User's Guide such that there is a [workflow diagram](https://mitiq.readthedocs.io/en/latest/contributing_docs.html#adding-workflow-images-to-the-user-guide) for the `new_QEM_method` on this page alongside
+links to any tutorials utilizing `new_QEM_method` in `docs/source/examples`. 
+
+```{code-block}
+   # Full Name of New QEM Method
+
+   One line summary of what the technique does
+
+   <start_backticks_code_block>{figure} ../img/new_qem_method_workflow.png
+   ---
+   width: 700px
+   name: new_qem_method_workflow_overview
+   ---
+   The new_QEM workflow in Mitiq is fully explained in the {doc}`new_QEM_method-4-low-level.md` section.
+   <end_backticks_code_block>
+
+   Below you can find sections of the documentation that address the following questions:
+
+   <start_backticks_code_block>{toctree}
+   ---
+   maxdepth: 1
+   ---
+   new_QEM_method-1-intro.md
+   new_QEM_method-2-use-case.md
+   new_QEM_method-3-options.md
+   new_QEM_method-4-low-level.md
+   new_QEM_method-theory.md
+   <end_backticks_code_block>
+
+   A simple tutorial using  `new_QEM_method` can be found <insert_link>
+```
+
+#### Adding workflow images to the user guide
 
 To insert a workflow to the user's guide of some new technique, a template is available (shown below as a `png`). This template is also available in `svg` format at [mitiq_template.svg](../source/img/general_template.svg).
 
@@ -108,14 +150,22 @@ Jupyter notebooks (`.ipynb`) or MyST markdown notebooks, but MyST formatting wil
 If you have a notebook you want to add, and want to automatically convert it from the `.ipynb` to `.md`, you can use a great Python command line tool called [jupytext](https://jupytext.readthedocs.io/en/latest/index.html).
 To convert from an IPython notebook to markdown file, run `jupytext your_filename.ipynb --to myst` and find the converted file at `your_filename.md`.
 
-Futher, not only can `jupytext` convert between the formats on demand, but once you install it, you can configure it to manage _both_ a Jupyter and Markdown version of your file, so you don't have to remember to do conversions (for more details, see the `jupytext` docs on [paired notebooks](https://jupytext.readthedocs.io/en/latest/index.html#paired-notebooks).
+Further, not only can `jupytext` convert between the formats on demand, but once you install it, you can configure it to manage _both_ a Jupyter and Markdown version of your file, so you don't have to remember to do conversions (for more details, see the `jupytext` docs on [paired notebooks](https://jupytext.readthedocs.io/en/latest/index.html#paired-notebooks)).
 Using the paired notebooks you can continue your development in the notebooks as normal, and just commit to git the markdown serialized version when you want to add to the docs.
 You can even add this tool as a [git pre-commit hook](https://jupytext.readthedocs.io/en/latest/using-pre-commit.html) if you want!
 
 ```{tip}
-There is a [sample markdown formatted notebook in the `examples` directory](./examples/template.md) for you to take a look at as you write your own!
+There is a [sample markdown formatted notebook in the `examples` directory](../source/examples/template.md) for you to take a look at as you write your own!
 ```
 
+### Adding example files
+
+If you are adding a new tutorial to the [documentation examples](../source/examples/examples.md),
+
+- add the file as a `.md` file in `docs/source/examples`. A template is available at [here](../source/examples/template.md).
+- add your tutorial in `docs/source/examples/examples.md` such that it shows up in a docs build 
+- add a thumbnail image as `docs/source/_thumbnails/your_image.png` and list it in the `nbsphinx_thumbnails` block of `docs/source/conf.py`
+
 ### Automatically add information from the API docs
 
 New modules, classes and functions can be added by listing them in the appropriate file (such as `apidoc.md` or a child), e.g.,
@@ -142,7 +192,7 @@ source code, and to the API page `apidoc.md`.
 
 ### Adding references 
 
-To add references to the [Mitiq bibliography](https://mitiq.readthedocs.io/en/stable/bibliography.html), the first step is to add the reference to `docs/source/refs.bib` which is organized alphabetically. For formatting, please see BibTeX documentation for [articles](https://www.bibtex.com/e/article-entry/), [books](https://www.bibtex.com/e/book-entry/), and [others](https://www.bibtex.com/e/entry-types/).
+To add references to the [Mitiq bibliography](bibliography.md), the first step is to add the reference to `docs/source/refs.bib` which is organized alphabetically. For formatting, please see BibTeX documentation for [articles](https://www.bibtex.com/e/article-entry/), [books](https://www.bibtex.com/e/book-entry/), and [others](https://www.bibtex.com/e/entry-types/).
 
 Once the reference has been added to the `docs/source/refs.bib` file, cite the reference in the file by using:
 ```md