Issue749

Title docs: add sections for plugins
Priority feature Status resolved
Superseder Nosy List cedric, gabi, guillem, jendrik, malte
Assigned To jendrik Keywords
Optional summary
part of issue727

Created on 2017-11-29.17:05:04 by jendrik, last changed by gabi.

Summary
part of issue727
Messages
msg7402 (view) Author: gabi Date: 2018-09-12.14:46:36
Reviewed and merged. 

I added issue816 for a wider application of this feature, copying Malte's last
comment on possible extensions.
msg7398 (view) Author: jendrik Date: 2018-09-12.14:15:39
Code and usage look good to me.
msg7396 (view) Author: malte Date: 2018-09-12.14:02:51
Silvan and I implemented the "explicit" sections, and this is ready for review.

It would be good if at minimum some interested parties can have a look at how
this is *used*, which is only 11 lines of very simple code, namely everything in
the pdbs directory in the pull request:

https://bitbucket.org/jendrikseipp/downward/pull-requests/79

If some also wants to review the implementation, of course that's fine, too. :-)
It was very straight-forward because it is very close to the other kinds of
plug-ins we had already. Like the existing code, the new code is not great, but
it is not great in a consistent way. ;-) We think that more general clean-up of
the option parser code is a matter for a different issue.

The explicit sections would also make it easier to add additional functionality
like section descriptions, explicitly influencing the order in which sections
appear, or documentation pages that speak about several different plug-in types
that are related. (Silvan thought of merge strategies and shrink strategies.) We
are not going there here, but maybe we can collect ideas for extensions
somewhere? Not sure how best to do it. Perhaps we don't want to open an issue
unless we have a concrete intention to do something.

Also, there should be a follow-up issue to use the section feature more heavily.
We just have a section for PDB heuristics at the moment so that we can test the
feature.
msg7389 (view) Author: malte Date: 2018-09-12.11:26:47
We discussed this live today and decided to have a go at the "explicit sections".
msg7381 (view) Author: malte Date: 2018-09-11.18:53:43
> I don't think we really need section IDs for now.

I'm not convinced. I think repeating the same text all the time will violate
DRY, and because we have dozens of plugins, it will be quite a violation. (I see
a difference between a "symbol" for a section and a "human-friendly title" for a
section there.) Once we start using sections, we will touch a large fraction of
the plug-ins (in dozens of files), so it would be nice not to have to do touch
all of them twice within a short period.

There are also drawbacks with having "section plug-ins", mainly that it is not
so obvious where they should live in the code.

I suggest discussing this with the interested parties tomorrow.
msg7376 (view) Author: jendrik Date: 2018-09-11.18:16:38
I added the PDB heuristics to their own section. I don't think we really need 
section IDs for now.
msg7375 (view) Author: cedric Date: 2018-09-11.16:44:25
Changed to the old behaviour.
msg7372 (view) Author: jendrik Date: 2018-09-11.16:25:19
I think we should use the old behaviour.
msg7370 (view) Author: cedric Date: 2018-09-11.15:58:39
I fixed the error in the documentation and pushed it to the pull request at
https://bitbucket.org/jendrikseipp/downward/pull-requests/79. But a new error
came up.

Before the fix, the documentation used the 'key' of a plugin if no
document_synopsis is given. Now it uses <missing> if we omit the
document_synopsis. What would be the best way to deal with this?
msg7362 (view) Author: malte Date: 2018-09-11.11:25:31
Correction: the correct version of course says "lmcut_constraints()", not
"lmcut()" as I said in my previous message.
msg7361 (view) Author: malte Date: 2018-09-11.11:13:30
I had a look at bitbucket. No detailed comments. (However, see below.)

To test this properly, we should exercise the new feature. Can you add all PDB
heuristics to a section "Pattern Databases" or similar?

Would it make sense to have each section have an ID and a title, rather than
just one string for both? For example, if I have a section "heuristics based on
saturated cost partitioning", then I think it may violate DRY to some extent to
have each heuristic in this section require this exact long string. It might be
nicer to have a "scp" tag instead. I realize this makes things harder to
implement because sections then need their own "identity" in the code. But that
would have further advantages, e.g. allowing documentation at the section level.
Discuss this further?

To test the code, I produced the docs and compared them to the docs before this
change, and they are broken. For example, instead of

== LM-cut landmark constraints ==
lmcut()

it now says

== LM-cut landmark constraints ==
LM-cut landmark constraints()

So obviously I overlooked something in the review. Could be a shadowing of local
vs. instance variables? I'll leave the search for the error for you, but if you
don't find it easily we can search it together.
msg6825 (view) Author: jendrik Date: 2018-03-14.13:53:13
I made a pull request at 
https://bitbucket.org/jendrikseipp/downward/pull-requests/79
and will add this to the review queue.
msg6631 (view) Author: jendrik Date: 2017-11-29.17:05:04
We want to add sections to the wiki documentation pages to group similar plugins.
History
Date User Action Args
2018-09-12 14:46:36gabisetstatus: reviewing -> resolved
nosy: + gabi
messages: + msg7402
2018-09-12 14:15:39jendriksetmessages: + msg7398
2018-09-12 14:02:51maltesetmessages: + msg7396
2018-09-12 11:26:47maltesetmessages: + msg7389
2018-09-11 18:53:43maltesetmessages: + msg7381
2018-09-11 18:16:38jendriksetmessages: + msg7376
2018-09-11 16:44:25cedricsetmessages: + msg7375
2018-09-11 16:25:19jendriksetmessages: + msg7372
2018-09-11 16:05:25guillemsetnosy: + guillem
2018-09-11 15:58:39cedricsetnosy: + cedric
messages: + msg7370
2018-09-11 11:25:31maltesetmessages: + msg7362
2018-09-11 11:13:31maltesetmessages: + msg7361
2018-03-14 13:53:13jendriksetstatus: unread -> reviewing
assignedto: jendrik
messages: + msg6825
2017-11-29 17:05:04jendrikcreate