Move larger code blocks in docs into their own files
Nobody has claimed this yet.
- 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:
- At present the code snippets in the docs are fragile.
- Change in the CUDA-Q programming model will make these code snippets obsolete over time.
- 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
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- 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