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.

Sign up for GitHub

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

Jump to bottom

Initial version of docs + HQAR -> QART rename #5

Merged
merged 26 commits into from
Apr 8, 2024
Merged

Initial version of docs + HQAR -> QART rename #5

merged 26 commits into from
Apr 8, 2024

Conversation

dexter2206
Copy link
Contributor

@dexter2206 dexter2206 commented Apr 5, 2024 •
edited
Loading

This PR renames HQAR to QART (both in Python package and in other places like e.g. README) and adds basic documentation built with mkdocs.

  1. To install dependencies needed for docs use poetry

    pip install poetry
poetry install --with docs

  2. To run local app serving docs run:

    mkdocs serve

  3. To build docs run:

    mkdocs build

Things that are missing in this PR (and will be added later):

  • More detailed description of the data format. We currently only have description of topology, without even mentioning resources and linked_params.
  • Deployment of docs (which we will add when we go public - private repositories cannot have GH pages website).

dexter2206 added 24 commits March 28, 2024 16:19
@dexter2206
Add docs stub
555be06
@dexter2206
Add language server info to mkdocs.yml
907e383
@dexter2206
Add basic docs structure
adfc704
@dexter2206
Add basic program/circuit example
1a72dd1
@dexter2206
Add short desription of QART format
367e9b1
@dexter2206
Add API reference
53849cf
@dexter2206
Update mkdocs.yml
9881510
@dexter2206
Remove copyright notices
8e31d19
@dexter2206
Rename hqar package to qart
1d19275
@dexter2206
Remove copyright checks
2239a81
@dexter2206
Remove remaining copyright notices
9b865cd
@dexter2206
Reorganize chapter on QART Python library
b9333d2
@dexter2206
Add content to index.md
fb117ed
@dexter2206
Add required plugins
7c6b706
@dexter2206
Reorganize docs for python library
88c89fd
@dexter2206
Remove whitespace
614a6da
@dexter2206
Update example yaml and svg (my_algorithm -> my_program)
11a129b
@dexter2206
Add basic development guide
95adc7a
@dexter2206
Update links in index.md
1b58308
@dexter2206
Add docs-related dependencies
cbb2c51
@dexter2206
Add more descriptions to format chapter
b1ee4a9
@dexter2206
Add job for building docs
bb40000
@dexter2206
Attempt running mkdocs through poetry run
c9a0240
@dexter2206
Add missing dependency on mkdocstrings
cbe8101
@dexter2206 dexter2206 requested a review from mstechly April 5, 2024 11:57
@mstechly
Copy link
Contributor

mstechly commented Apr 7, 2024 •
edited
Loading

Just from trying to run it:

  1. poetry install --with-docs option doesn't work. Running poetry install itself worked just fine though. Also, just noticed – you got an extra - there, --with docs works well.
  2. Looks like links to images are broken – when I run mkdocs serve I get: WARNING - Doc file 'format.md' contains a relative link 'images/basic_program.svg', but the target is not found among documentation files.

mstechly
mstechly requested changes Apr 7, 2024
View reviewed changes
Copy link
Contributor

@mstechly mstechly left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Overall looks good, some minor comments.
However, it seems to me that a couple of things are missing (perhaps you want to add them in a separate PR, if that's the case it's fine):

  • The following are undocumented: resources, input_params, local_variables, linked_params, meta
  • The big AliasSampling example is missing
  • It would be good to also have a section in the docs about known limitations, such as repetitions or mid-circuit measurements. Or the fact that it's not intended to be executable.

docs/format.md

Representing such a circuit as a graph is straightforward, it might look like this:

![example_routine](images/basic_program.svg)
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

[issue] I think you forgot to add some of the pictures.

docs/format.md Outdated Show resolved Hide resolved
docs/format.md Outdated
- `name`: Mandatory name of the program, here set to the string `my_program`.
- `ports`: A collection of ports. For most of the time, not much is lost by
thinking of them as of quantum registers.
- `children`: A list of children, or subroutines of the program.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

"," after subroutines.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Fixed in d2b5e87

docs/format.md Outdated Show resolved Hide resolved
docs/format.md

Ports, like most other components in QART, have names, which should be distinct
among all ports of any given program (or subroutine). Each port also has
direction, which can be either `input` or `output`. Finally, each port has size.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

It can also be through.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'd rather not mention through at this point because:

  1. We don't support through in compilation.
  2. We don't support through when drawing.
  3. We doin't have example using through.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

That's fine. You got me with the doin't.

@dexter2206
Copy link
Contributor Author

Overall looks good, some minor comments. However, it seems to me that a couple of things are missing (perhaps you want to add them in a separate PR, if that's the case it's fine):

  • The following are undocumented: resources, input_params, local_variables, linked_params, meta
  • The big AliasSampling example is missing
  • It would be good to also have a section in the docs about known limitations, such as repetitions or mid-circuit measurements. Or the fact that it's not intended to be executable.

Thanks @mstechly ! I added missing images and applied your suggestions. As for the missing content, I plan to add it in a separate PR, because I didn't want to further delay this already late one.

mstechly
mstechly approved these changes Apr 8, 2024
View reviewed changes
Copy link
Contributor

@mstechly mstechly left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Looks good now!

@dexter2206 dexter2206 merged commit 3240e66 into main Apr 8, 2024
6 checks passed
@dexter2206 dexter2206 deleted the kj/material-docs branch April 8, 2024 13:42
mstechly pushed a commit that referenced this pull request Apr 24, 2024
@dexter2206 @mstechly
Initial version of docs + rename (#5)
ac388d1 
* Add docs stub

* Add language server info to mkdocs.yml

* Add basic docs structure

* Add basic program/circuit example

* Add short desription of QART format

* Add API reference

* Update mkdocs.yml

* Remove copyright notices

* Rename hqar package to qart

* Remove copyright checks

* Remove remaining copyright notices

* Reorganize chapter on QART Python library

* Add content to index.md

* Add required plugins

* Reorganize docs for python library

* Remove whitespace

* Update example yaml and svg (my_algorithm -> my_program)

* Add basic development guide

* Update links in index.md

* Add docs-related dependencies

* Add more descriptions to format chapter

* Add job for building docs

* Attempt running mkdocs through poetry run

* Add missing dependency on mkdocstrings

* Apply changes suggested in the review

* Add missing images
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Reviewers

@mstechly mstechly mstechly approved these changes

Assignees
No one assigned
Labels
None yet
Milestone
No milestone
Development

Successfully merging this pull request may close these issues.
2 participants
@dexter2206 @mstechly