Docs: Move in section on QueryBuilder to How-To #4080

mbercx · 2020-05-18T12:23:33Z

Move in the sections on the QueryBuilder to the 'Finding and querying for data' How-to of the revamped documentation.

Changes quite a bit of the section on the appender method:

Switches the examples to simple ones that are based on the ArithmeticAddCalculation process.
Gives the text a large overhaul. The text tries to be consistent in terminology, but this can probably still be improved. We should try and introduce terms like 'vertex', 'edge', etc. when they are first mentioned.

The section on the queryhelp has been largely left 'as is', save for the introduction and some reformatting along the new style guidelines.

mbercx · 2020-05-18T12:31:12Z

I'm still not 100% happy with the current text, but I figured it would be good to first get some feedback on the content. Some open questions in this regard:

The How-To section now only explains the use of the QueryBuilder. Should other ways of finding data be discussed here?
The How-To is now rather long. Is this an issue?
How detailed should the section on the queryhelp be?

csadorf

Thank you very much! I've provided some comments and suggestions. I suggest that we address those first and then we revisit your concerns.

docs/source/howto/data.rst

sphuber · 2020-05-19T10:32:06Z

I was just discussing with @mbercx and we think the current page for the QueryBuilder is too extensive for the how-to. We were thinking then to move the existing content to a "Topic" section, with complete and detailed information on the builder and have a distilled version for the How-to section that really focuses on the basics. @csadorf and @ltalirz what do you think?

csadorf · 2020-05-19T10:52:26Z

I was just discussing with @mbercx and we think the current page for the QueryBuilder is too extensive for the how-to. We were thinking then to move the existing content to a "Topic" section, with complete and detailed information on the builder and have a distilled version for the How-to section that really focuses on the basics. @csadorf and @ltalirz what do you think?

I agree notwithstanding that some of the content would better be placed within the reference chapter (see related comments).

docs/source/howto/data.rst

mbercx · 2020-05-26T12:55:29Z

Thanks @csadorf and @sphuber for the comments! To distill the how-to, I was thinking of limiting the sections to the following:

Selecting entities
Retrieving results
Filters
Relationships
Projections

And moving the other sections to the topics, perhaps under "advanced querying"?

For the reference section, do I simply make a querybuilder page in the top level reference section, or should this be part of a larger page that also contains references for other parts of the documentation?

csadorf · 2020-05-26T16:56:28Z

Thanks @csadorf and @sphuber for the comments! To distill the how-to, I was thinking of limiting the sections to the following:

Selecting entities

Retrieving results

Filters

Relationships

Projections

And moving the other sections to the topics, perhaps under "advanced querying"?

I think I need to see this to be really able to make a call. Maybe give it a shot and we see how it pans out?

For the reference section, do I simply make a querybuilder page in the top level reference section, or should this be part of a larger page that also contains references for other parts of the documentation?

Since the QueryBuilder is part of the Python API, I'd document this as part of the class doc-string and link there.

docs/source/howto/data.rst

csadorf · 2020-05-27T09:49:34Z

I think this has the right length and scope now. I am really happy with the section now.

sphuber

Thanks a lot @mbercx . Really like the structure, scope and length. Just have some suggestions. Also do not forget to make clear here that we are only moving part of the existing docs, that is rephrased as well, and not all the content that is removed is addressed here. But you will do this in a separate PR for another issue. Would be good to link it once we decided which issue it will be

docs/source/howto/data.rst

mbercx · 2020-05-27T18:32:50Z

Thanks again @sphuber and @csadorf for the suggestions and discussion! A few notes:

The links to the "advanced queries" topics section do not work, as the target link is in another branch. I'll try to clean this branch up and create a PR tomorrow.
I've rewritten the projection subsection, to separate the last-entity and instances behaviour. Hopefully this is now less confusing.

sphuber

Honest to god, these are the last two comments :) and then we can merge

sphuber · 2020-05-27T20:39:02Z

docs/source/howto/data.rst

@@ -404,4 +659,4 @@ Notice that we haven't specified any port in the URLs since Apache listens conve

 .. _#3996: https://github.com/aiidateam/aiida-core/issues/3996
 .. _#3997: https://github.com/aiidateam/aiida-core/issues/3997
-.. _#3998: https://github.com/aiidateam/aiida-core/issues/3998
+.. _#3998: https://github.com/aiidateam/


This is an accidental change I imagine? You can restore this and actually remove the link for 3996, which is the one this PR solves

Yes, this was accidental. I must have gotten a little overzealous while slimming down the section. ^^

sphuber · 2020-05-27T20:40:00Z

docs/source/howto/data.rst

+
+    qb = QueryBuilder()
+    qb.append(CalcJobNode, tag='calcjob')
+    qb.append(Int, with_incoming='calcjob', project=['id', '*', 'attributes.value'])


Just wondering: projecting both the instance and separate values might not make the most sense in most cases, as you can always get those properties from the instance once loaded. Note sure if it matters here, or if this slightly weird example may cause some confusion

Fair point! The idea was to introduce project='*' to another query to show that you can use '*' like any other projection. I've moved this concept to the next query example.

csadorf

Perfect ! 👍

sphuber · 2020-05-28T07:50:03Z

Promises Made - Promises Kept 😉

Thanks @mbercx !

Move in the sections on the `QueryBuilder` to the How-to section called "Finding and querying for data" The original text was too extensive for the purposes of the How-to and so it has been split in two. The detailed information on advanced queries will be added in another PR in the section "Topic - Database". The text for this How-to has been adapted from the original text with significant changes in the structure and simplifying the examples. Here wherever possible they use the `ArithmeticAddCalculation` for consistency with other sections and tutorials. The new structure is as follows: * Selecting entities * Retrieving results * Filters * Relationships * Projections

mbercx added the topic/documentation label May 18, 2020

mbercx added this to the Publish revised documentation milestone May 18, 2020

mbercx requested review from ltalirz and csadorf May 18, 2020 12:31

csadorf reviewed May 18, 2020

View reviewed changes

csadorf removed this from the Publish revised documentation milestone May 18, 2020

sphuber reviewed May 20, 2020

View reviewed changes

docs/source/howto/data.rst Outdated Show resolved Hide resolved

mbercx linked an issue May 25, 2020 that may be closed by this pull request

Docs: How to find data #3996

Closed

mbercx force-pushed the fix/3996/docs-howto-find-data branch from aa404e6 to 7252417 Compare May 26, 2020 16:39

mbercx requested a review from csadorf May 26, 2020 19:05

csadorf suggested changes May 27, 2020

View reviewed changes

sphuber requested changes May 27, 2020

View reviewed changes

mbercx added 3 commits May 27, 2020 20:21

Docs: Add how-to on finding/querying data

a7a6e83

Docs: slim down finding data how-to

ad9f825

Apply reviewer suggestions

b502de0

mbercx force-pushed the fix/3996/docs-howto-find-data branch from 02dd9ad to b502de0 Compare May 27, 2020 18:27

sphuber requested changes May 27, 2020

View reviewed changes

Apply (final?) reviewer suggestions

2e833f1

mbercx requested a review from sphuber May 28, 2020 07:10

sphuber approved these changes May 28, 2020

View reviewed changes

csadorf approved these changes May 28, 2020

View reviewed changes

sphuber merged commit 005acdf into aiidateam:docs-revamp May 28, 2020

sphuber mentioned this pull request May 28, 2020

Docs: How to find data #3996

Closed

mbercx deleted the fix/3996/docs-howto-find-data branch May 28, 2020 08:15

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Docs: Move in section on QueryBuilder to How-To #4080

Docs: Move in section on QueryBuilder to How-To #4080

mbercx commented May 18, 2020

mbercx commented May 18, 2020

csadorf left a comment

sphuber commented May 19, 2020

csadorf commented May 19, 2020

mbercx commented May 26, 2020 •

edited

Loading

csadorf commented May 26, 2020

csadorf commented May 27, 2020

sphuber left a comment

mbercx commented May 27, 2020

sphuber left a comment

sphuber May 27, 2020

mbercx May 28, 2020

sphuber May 27, 2020

mbercx May 28, 2020

csadorf left a comment

sphuber commented May 28, 2020

Docs: Move in section on QueryBuilder to How-To #4080

Docs: Move in section on QueryBuilder to How-To #4080

Conversation

mbercx commented May 18, 2020

mbercx commented May 18, 2020

csadorf left a comment

Choose a reason for hiding this comment

sphuber commented May 19, 2020

csadorf commented May 19, 2020

mbercx commented May 26, 2020 • edited Loading

csadorf commented May 26, 2020

csadorf commented May 27, 2020

sphuber left a comment

Choose a reason for hiding this comment

mbercx commented May 27, 2020

sphuber left a comment

Choose a reason for hiding this comment

sphuber May 27, 2020

Choose a reason for hiding this comment

mbercx May 28, 2020

Choose a reason for hiding this comment

sphuber May 27, 2020

Choose a reason for hiding this comment

mbercx May 28, 2020

Choose a reason for hiding this comment

csadorf left a comment

Choose a reason for hiding this comment

sphuber commented May 28, 2020

mbercx commented May 26, 2020 •

edited

Loading