Docs: add documentation for GroupPath

[chrisjsewell]

closes #3913

[codecov]

Codecov Report

Merging #3952 into develop will increase coverage by 0.01%.
The diff coverage is n/a.

@@             Coverage Diff             @@
##           develop    #3952      +/-   ##
===========================================
+ Coverage    78.45%   78.45%   +0.01%     
===========================================
  Files          461      461              
  Lines        34077    34077              
===========================================
+ Hits         26731    26732       +1     
+ Misses        7346     7345       -1     

Flag	Coverage Δ
#django	70.50% <ø> (+0.01%)	⬆️
#sqlalchemy	71.35% <ø> (ø)

Impacted Files	Coverage Δ
aiida/transports/plugins/local.py	80.47% <0.00%> (+0.26%)	⬆️

---

Continue to review full report at Codecov.

Legend - Click here to learn more
Δ = absolute <relative> (impact), ø = not affected, ? = missing data
Powered by Codecov. Last update f7ac506...3cc9a03. Read the comment docs.

[ltalirz]

Thanks a lot @chrisjsewell , this looks very useful!

My main question here would be whether this is understandable to a newcomer, and so may I suggest that instead of @sphuber perhaps @mbercx gives this a review?

[mbercx]

Very clear, thanks Chris! The examples really help for understanding the concepts. I wasn't aware of this feature, and now I'll definitely be using it going forward. :)

One part that was a little confusing is how you can create and delete Groups via the GroupPath. It wasn't immediately clear up to that point that you can construct GroupPaths that don't exist, but I suppose that's why they are virtual.

Another small note: Are you sure the output of Out[10] is correct? It should probably be False, considering the next line.

[sphuber]

Thanks @chrisjsewell , since @mbercx already reviewed on the intelligibility, I won't comment on that. Seems fine. Just to reiterate his question whether the one statement is correct. Besides that, two more requests:

• Could you please add a sentence or two on the function of cls in the GroupPath and the current limitations?
• Please maintain one sentence per line for text.

[chrisjsewell]

Please maintain one sentence per line for text.

Do you mean converting this:

You can also traverse directly through the nodes of a path,
optionally filtering by node class and any other filters allowed by the `QueryBuilder`::

to this:

You can also traverse directly through the nodes of a path, optionally filtering by node class and any other filters allowed by the `QueryBuilder`::

because you end up with quite long lines, which is why I'd added a few breaks on commas.

[chrisjsewell]

Could you please add a sentence or two on the function of cls in the GroupPath and the current limitations?

Added in 506a6c6

[CasperWA]

Should this be added before revamping the docs?

[chrisjsewell]

I think so. Its ready for merging IMO

[sphuber]

because you end up with quite long lines, which is why I'd added a few breaks on commas.

Yes, that is what I mean, because that is the style rule that was decided. We should not add arbitrary line breaks but just let the editor use soft line-wrapping.

Regarding the merging. Since anyway this will have to be moved once we have the new skeleton, there is no rush right? Since it is purely adding new text, there won't be any merge conflicts. So I actually would hold off with merging this until the skeleton is inplace, and then we can add it in the correct place straight away. Doing the same with my open docs PR #3966

[chrisjsewell]

Please maintain one sentence per line for text.

Fixed in 3cc9a03

[CasperWA]

Regarding the merging. Since anyway this will have to be moved once we have the new skeleton, there is no rush right? Since it is purely adding new text, there won't be any merge conflicts. So I actually would hold off with merging this until the skeleton is inplace, and then we can add it in the correct place straight away. Doing the same with my open docs PR #3966

Fine. Then I'll add it to the project instead.

[csadorf]

@chrisjsewell Could you adapt this PR so that we can merge it into docs-revamp?

[chrisjsewell]

Could you adapt this PR so that we can merge it into docs-revamp?

On it now 👍

[chrisjsewell]

rebased to #4126