NVIDIA / NVIDIA/cuda-quantum

Move larger code blocks in docs into their own files

Open
#710 6 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

documentation good first issue stale-notified
Dominant language
C++
Stars
1.1k
Forks
455
Avg merge
1d 22h
Merged PRs (30d)
165

Description

Goal:
Create examples files for code snippets (C++, Python) found in CUDA-Q docs. Replace those code snippets in the docs with the inclusion of the file or selective lines from the file.

Refer CUDA-Q document: https://nvidia.github.io/cuda-quantum/latest/using/quick_start.html

Issue:

  1. At present the code snippets in the docs are fragile.
  2. Change in the CUDA-Q programming model will make these code snippets obsolete over time.
  3. reStructuredText (rst) file should not contain the hardcoded part as can be seen in examples.rst file.

Solution:
Create examples files for these code snippets.
Add tests for the newly created examples files.
Include these files or selective lines from these files in the docs using literalinclude.
Add these files to run as part of CI.

Resources:
C++ code snippets: https://github.com/NVIDIA/cuda-quantum/tree/main/docs/sphinx/snippets/cpp
Python code snippets: https://github.com/NVIDIA/cuda-quantum/tree/main/docs/sphinx/snippets/python
Tests for code snippets: https://github.com/NVIDIA/cuda-quantum/blob/main/docs/CMakeLists.txt

Notes:
Please see the attached file which shows examples available only for C++ and only for Python.
Code snippets in C++ and Python

Additional information:
Here is a list of .rst files with code-blocks. We would like to move the code out of these code-blocks into their own files (.cpp or .py).

File name                                    Path

default_ops.rst                      docs/sphinx/api
cpp_api.rst                          docs/sphinx/api/languages
python_api.rst                       docs/sphinx/api/languages
algorithmic_primitives.rst           docs/sphinx/specification/cudaq
examples.rst                         docs/sphinx/specification/cudaq
kernels.rst                          docs/sphinx/specification/cudaq
operations.rst                       docs/sphinx/specification/cudaq
operators.rst                        docs/sphinx/specification/cudaq
patterns.rst                         docs/sphinx/specification/cudaq
platform.rst                         docs/sphinx/specification/cudaq
synthesis.rst                        docs/sphinx/specification/cudaq
types.rst                            docs/sphinx/specification/cudaq
_noise.rst                           docs/sphinx/using/extending
cudaq_ir.rst                         docs/sphinx/using/extending
cuda_gpu.rst                         docs/sphinx/using/integration

For example, in the examples.rst file, the following code-block should be moved into its own .cpp file and needs to be added as part of CI in docs/CMakeLists.

.. code-block:: cpp

     #include <cudaq.h>

     struct bell {
       int operator()(int num_iters) __qpu__ {
         cudaq::qarray<2> q;
         int nCorrect = 0;
         for (int i = 0; i < num_iters; i++) {
           h(q[0]);
           x<cudaq::ctrl>(q[0], q[1]);
           auto results = mz(q);
           if (results[0] == results[1])
             nCorrect++;
          
           reset(q[0]);
           reset(q[1]);
         }
         return nCorrect;
       }
     };

     int main() { printf("N Correct = %d\n", bell{}(100)); }

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Start by reviewing docs/CMakeLists and the existing snippets under docs/sphinx/snippets/cpp and docs/sphinx/snippets/python, then inspect the listed .rst files for code blocks. Move the relevant C++ and Python examples into files, replace the blocks with literalinclude directives, and add the examples to the snippet tests and CI.

Written by the indexing model from the issue text.

Assessment

Tech stack
cmake, cpp, python
Domain
build-system, ci-cd, documentation, testing-qa
Issue type
Documentation
Difficulty
4/5
Estimated time
3-5 days
Activity status
Stale
Clarity
Mostly clear
Newbie friendliness
42/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.