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.

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

DOC: Improve documentation for nodes #57

Closed
mpu-creare opened this issue Jun 11, 2018 · 2 comments
Closed

DOC: Improve documentation for nodes #57

mpu-creare opened this issue Jun 11, 2018 · 2 comments
Projects

Comments

@mpu-creare
Copy link
Contributor

@mpu-creare mpu-creare commented Jun 11, 2018

Description
Right now the constructor to nodes is not useful in terms of actual documentation since no sub-node actually uses the __init__ constructor directly

Describe the solution you'd like
Improve the documentation. Both user documentation and docstrings.
Make a traitlets starter guide.

@jmilloy
Copy link
Collaborator

@jmilloy jmilloy commented Jun 11, 2018

After reviewing the traitlets refactor #55, I think that an essential part of this is to have a standardized way to list specifically the attrs and params in the docstrings for Nodes (in addition to the normal Attributes section).

I don't know Sphinx well, but we could add custom sections for attrs and params, right? It would be cool if it could Sphinx introspect for attr and param tags, but that seems like to much to ask for.

It think these sections would include all tagged attrs and params from parent Nodes, so that anyone just trying to use a particular Node can quickly find the attrs they can set and the params they can evaluate with. I think that would address the issues @mlshapiro brought up, while more advanced users who are writing custom Nodes would be more familiar using traitlets and with finding documentation for inherited class attributes.

Note

  • attrs are set at Node instantiation and then cannot be changed. You can set defaults in the class definition.
  • params are passed in when executing the node (so you can execute a node multiple times with different params). You can set defaults in the class definition and at class instantiation.

@mpu-creare mpu-creare added this to the 0.2.0 milestone Aug 13, 2018
@mpu-creare mpu-creare added this to Ready in 0.2.0 Release Aug 13, 2018
@mpu-creare mpu-creare removed this from Ready in 0.2.0 Release Oct 8, 2018
@mpu-creare mpu-creare added this to To do in 0.2.1 Release Oct 8, 2018
@mpu-creare mpu-creare added this to To do in 0.2.2 via automation Nov 19, 2018
@mpu-creare mpu-creare removed this from To do in 0.2.1 Release Nov 19, 2018
@mpu-creare mpu-creare removed this from the 0.2.0 milestone Nov 19, 2018
@mpu-creare
Copy link
Contributor Author

@mpu-creare mpu-creare commented Dec 3, 2018

see #176

@mpu-creare mpu-creare closed this Dec 3, 2018
0.2.2 automation moved this from To do to Done Dec 3, 2018
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
No open projects
0.2.2
  
Done
Development

No branches or pull requests

2 participants