tket icon indicating copy to clipboard operation
tket copied to clipboard

Published 20 hours ago • verified publisher icon CQCL

[DRAFT] Fix some API docs omissions

Open CalMacCQ opened this issue 1 year ago • 5 comments

Description

After running the sphinx coverage extension with

sphinx-build -b coverage pytket/docs/ pytket/docs/build/

I found some omissions from the API docs.

Some of these omissions are not user facing and should probably be underscored functions/classes.

Leaving aside some functions implementing symbolic gates the ouput I got was the following

undocumented  py  class     BarrierOp                      - in module pytket._tket.circuit
undocumented  py  method    Circuit.add_wasm               - in module pytket._tket.circuit
undocumented  py  method    Circuit.add_wasm_to_reg        - in module pytket._tket.circuit
undocumented  py  class     EdgeType                       - in module pytket._tket.circuit
undocumented  py  class     MetaOp                         - in module pytket._tket.circuit
undocumented  py  function  fully_connected_backendinfo    - in module pytket.backends.backendinfo
undocumented  py  function  get_TK1_decomposition_function - in module pytket.passes.auto_rebase
undocumented  py  function  get_cx_decomposition           - in module pytket.passes.auto_rebase
undocumented  py  function  get_tk2_decomposition          - in module pytket.passes.auto_rebase
undocumented  py  class     NoAutoRebase                   - in module pytket.passes.auto_rebase
undocumented  py  function  reduce_matrices                - in module pytket.utils.spam
undocumented  py  function  reduce_matrix                  - in module pytket.utils.spam

Weirdly Circuit.add_wasm and Circuit.add_wasm_to_reg show up even though they have documentation.

Besides these two I don't think any of these other functions or classes need to be user facing.

Related issues

~~Fixes #1265~~ addressed by #1282

Checklist

  • [x] I have performed a self-review of my code.
  • [ ] I have commented hard-to-understand parts of my code.
  • [ ] I have made corresponding changes to the public API documentation.
  • [ ] I have added tests that prove my fix is effective or that my feature works.
  • [ ] I have updated the changelog with any user-facing changes.

CalMacCQ avatar Mar 05 '24 13:03 CalMacCQ 

undocumented  py  class     BarrierOp                      - in module pytket._tket.circuit
undocumented  py  method    Circuit.add_wasm               - in module pytket._tket.circuit
undocumented  py  method    Circuit.add_wasm_to_reg        - in module pytket._tket.circuit
undocumented  py  class     EdgeType                       - in module pytket._tket.circuit
undocumented  py  class     MetaOp                         - in module pytket._tket.circuit
undocumented  py  function  fully_connected_backendinfo    - in module pytket.backends.backendinfo
undocumented  py  function  get_TK1_decomposition_function - in module pytket.passes.auto_rebase
undocumented  py  function  get_cx_decomposition           - in module pytket.passes.auto_rebase
undocumented  py  function  get_tk2_decomposition          - in module pytket.passes.auto_rebase
undocumented  py  class     NoAutoRebase                   - in module pytket.passes.auto_rebase
undocumented  py  function  reduce_matrices                - in module pytket.utils.spam
undocumented  py  function  reduce_matrix                  - in module pytket.utils.spam

@cqc-alec do any of the above belong in the public API docs? (Besides the circuit wasm methods) They seem like mostly internal methods and classes.

CalMacCQ avatar Mar 11 '24 15:03 CalMacCQ 

undocumented  py  class     BarrierOp                      - in module pytket._tket.circuit
undocumented  py  method    Circuit.add_wasm               - in module pytket._tket.circuit
undocumented  py  method    Circuit.add_wasm_to_reg        - in module pytket._tket.circuit
undocumented  py  class     EdgeType                       - in module pytket._tket.circuit
undocumented  py  class     MetaOp                         - in module pytket._tket.circuit
undocumented  py  function  fully_connected_backendinfo    - in module pytket.backends.backendinfo
undocumented  py  function  get_TK1_decomposition_function - in module pytket.passes.auto_rebase
undocumented  py  function  get_cx_decomposition           - in module pytket.passes.auto_rebase
undocumented  py  function  get_tk2_decomposition          - in module pytket.passes.auto_rebase
undocumented  py  class     NoAutoRebase                   - in module pytket.passes.auto_rebase
undocumented  py  function  reduce_matrices                - in module pytket.utils.spam
undocumented  py  function  reduce_matrix                  - in module pytket.utils.spam

@cqc-alec do any of the above belong in the public API docs? (Besides the circuit wasm methods) They seem like mostly internal methods and classes.

BarrierOp and MetaOp should be, as should fully_connected_backendinfo. Probably NoAutoRebase as well. The others probably not.

cqc-alec avatar Mar 11 '24 16:03 cqc-alec

BarrierOp and MetaOp should be, as should fully_connected_backendinfo. Probably NoAutoRebase as well. The others probably not.

Ah okay, I was under the impression that fully_connected_backendinfo was for testing only. Can add it back in.

CalMacCQ avatar Mar 11 '24 17:03 CalMacCQ

I've now added the following additonal classes and functions to the API docs

  • fully_connected_backendinfo
  • NoAutoRebase
  • BarrierOp
  • MetaOp

There are a couple more things to do.

  1. Add EdgeType to API docs or get sphinx.ext.coverage to ignore it
  2. Figure out why Circuit.add_wasm and Circuit.add_wasm_to_reg are showing up even though they have documentation.
  3. Get sphinx.ext.coverage to ignore underscored methods. Can probably do this by providing a regex pattern. The extension is poorly documented which is ironic.
  4. It would also be nice to do this coverage check as part of the CI checks. This would mean that if new functions or classes are added to the source code without being added to the API docs we will get a CI failure.
  5. Once I've added all of the user facing functions and classes to the docs make everything else undercored.

If preferred I can split this into separate PRs

CalMacCQ avatar Mar 11 '24 18:03 CalMacCQ

BarrierOp and MetaOp should be, as should fully_connected_backendinfo. Probably NoAutoRebase as well. The others probably not.

Ah okay, I was under the impression that fully_connected_backendinfo was for testing only. Can add it back in.

It is being used here for example.

cqc-alec avatar Mar 12 '24 08:03 cqc-alec

Found yet more omissions with pytket v1.27.0 using the check_circuit_class_docs.py script.

['add_circbox_regwise', 'AAMS', 'GPI', 'add_circbox_with_regmap', 'GPI2', 'add_termsequencebox']

Rather annoying that the sphnx coverage extension didn't find these.

added the missing methods in https://github.com/CQCL/tket/pull/1271/commits/d2cfc4febbea6a2356e188853dee7af2214065cb

CalMacCQ avatar Apr 17 '24 00:04 CalMacCQ