Comments (3)
Yea this (and related topics) is something we've discussed several times. The Google style guide suggests that the parameters should only be described in __init__
, whereas the class docstring should just give an overview of the class (and also any public attributes, which we rarely document).
I am generally for removing duplicated documentation - it greatly increases our ability to maintain the code. Basically any time we find ourselves copy-pasting docstrings, I would rather do something else. One thing I've been playing around with in other projects is using See Also
blocks or just saying that other parameters are documented in :meth:some_other_func
. This has the disadvantage of having to manually searching for that function while developing (although IDEs may lower this barrier some), but has the advantage that Sphinx will create hyperlinks to that function in the autogenerated documentation. This is particularly helpful for parameters that are just being plumbed through to other functions. As my current goal basically is to make the ReadTheDocs the one-stop shop for all pyGSTi documentation (both tutorials and API reference), the pros of doing this referencing/linking greatly outweigh the cons for me, but I'm open to being convinced otherwise.
from pygsti.
I also remember @rileyjmurray talking about docstring templates at some point, but can't remember the exact context.
from pygsti.
I'm also fine with removing duplicated documentation. In this case I think that straight-up deleting the class docstrings and keeping in __init__
is reasonable.
Responding to Stefan's last comment, here's a super simple decorator definition that can programmatically populate docstrings:
def set_docstring(docstr):
def assign(fn):
fn.__doc__ = docstr
return fn
return assign
Here's how I used it in other projects. The idea was to define an interface class that included a template docstring with a few blank spots, then subclasses would define a tuple of strings called that held content to substitute into the template.
class TaskInterface:
"""
Class for doing the useful thing.
"""
TEMPLATE_DOCSTR = """
Given x and y, approximately compute
the_thing(x, y).
%s
Parameters
------------
x : something
y : something
tol : float
%s
Returns
--------
val : something
%s
"""
# Dummy values
INTERFACE_FIELDS = (
"""
Use [the method].
""",
"""
We use an iterative method, and stop once [metric] falls below tol.
""",
"""
Note, "val" is guaranteed to satisfy [condition].
"""
)
DOCSTR = TEMPLATE_DOCSTR % INTERFACE_FIELDS
@set_docstring(DOCSTR)
def __call__(x, y, tol):
raise NotImplementedError()
from pygsti.
Related Issues (20)
- Pickles are Bad, JSON is Good
- Deprecation of DenseOperatorInterface
- Investigate benefits of ``__slots__`` for core classes
- Audit code for use of list comprehensions where generators would be faster HOT 2
- Forward Simulator Dprobs Bugs with Instruments
- Audit usage of linalg.inv
- Error gen projection basis must be Basis object HOT 1
- Method `parameter_labels()` returns an empty array HOT 1
- 1/2 Diamond Norm Errorbars
- Raw Estimates Errorbars for TPInstrument HOT 1
- CP Instruments & Instrument Error Generators
- QI Report Fixes & Additions
- Wildcard w/ QILGST
- Fisher Information w/ Experiment Designs Containing MCMs
- Explicit Model Construction from MCM-Containing Pspec
- Help with detecting crosstalk errors of simulated data
- Serialization Issue w/ Processor Spec Nonstd_Instruments HOT 1
- Numpy version dependency HOT 1
- Gswap cannot be used as a two-qubit standard native gate for two-qubit RB as CliffordCompilationRules taking too long
- Line label reordering during `Circuit` concatenation
Recommend Projects
-
React
A declarative, efficient, and flexible JavaScript library for building user interfaces.
-
Vue.js
🖖 Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.
-
Typescript
TypeScript is a superset of JavaScript that compiles to clean JavaScript output.
-
TensorFlow
An Open Source Machine Learning Framework for Everyone
-
Django
The Web framework for perfectionists with deadlines.
-
Laravel
A PHP framework for web artisans
-
D3
Bring data to life with SVG, Canvas and HTML. 📊📈🎉
-
Recommend Topics
-
javascript
JavaScript (JS) is a lightweight interpreted programming language with first-class functions.
-
web
Some thing interesting about web. New door for the world.
-
server
A server is a program made to process requests and deliver data to clients.
-
Machine learning
Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.
-
Visualization
Some thing interesting about visualization, use data art
-
Game
Some thing interesting about game, make everyone happy.
Recommend Org
-
Facebook
We are working to build community through open source technology. NB: members must have two-factor auth.
-
Microsoft
Open source projects and samples from Microsoft.
-
Google
Google ❤️ Open Source for everyone.
-
Alibaba
Alibaba Open Source for everyone
-
D3
Data-Driven Documents codes.
-
Tencent
China tencent open source team.
from pygsti.