Refactor manual to better include contributed modules #253
Comments
|
I think i like the idea of the self containing manual for the modules at the same time I think the best would be to have everything accessible from both places e.g a Pippo_bias will also automatically appear inside the general biases list as well as in the Pippo module pages |
- if something is called @XXX_YYY@ then is considered as a distinct plumed module - then there is a page XXX.md which links to the YYY subpages. Furthermore if YYY is COLVAR, FUNCTION, BIAS or any of the common plumed keywords then these are also listed in the appropriate section of the manual @GiovanniBussi do you think it can work?
|
I think so. Just a question: in case Pippo_bias is of type bias, you put the \subpage in the module page and the \ref in the bias page, right? I think this would be the correct way. Finally, maybe one could replace this: with this: just to avoid troubles if someone puts the keyword |
|
At the moment I am using subpage for both, with \ref it does not appear in the list otherwise (or more probably I don’t know how to do it)
Anyway in the index of action it is related to the one in the module.
This is how it looks at the moment:
https://plumed.github.io/doc-isdb/user-doc/html/index.html <https://plumed.github.io/doc-isdb/user-doc/html/index.html>
While I have replaced the grep with yours.
… On 19 Jul 2017, at 18:06, Giovanni ***@***.***> wrote:
I think so. Just a question: in case Pippo_bias is of type bias, you put the \subpage in the module page and the \ref in the bias page, right? I think this would be the correct way.
Finally, maybe one could replace this:
keywords=`grep "^ *@" *.md | awk -F"@" '{print $2}' | uniq`
with this:
grep -o ***@***.***_]*@" *.md | awk -F"@" '{print $2}' | uniq
just to avoid troubles if someone puts the keyword @colvar@ not at the beginning
of the line.
—
You are receiving this because you commented.
Reply to this email directly, view it on GitHub <#253 (comment)>, or mute the thread <https://github.com/notifications/unsubscribe-auth/AEXl9h0Z7gjxRrMgxgYmi5HRhmUtsm1lks5sPilogaJpZM4OH7G4>.
|
|
I see, maybe Doxygen is clever enough to create the page only once... Looking at the manual I am not completely sure that it makes sense to have actions repeated Maybe an alternative could be to add e.g. at the end of the bias page a sentence such as Here Could this make sense? |
|
I would prefer as it now because a bias is a bias irrespectively of the module where it is implemented. Furthermore as it is now it requires less work, essentially the only step that is not automatic is to add ISDBPP.md in the go-doxygen.
… On 19 Jul 2017, at 18:29, Giovanni ***@***.***> wrote:
I see, maybe Doxygen is clever enough to create the page only once...
Looking at the manual I am not completely sure that it makes sense to have actions repeated
(in the left menu). To me the confusing thing is indeed that when you expand the tree on the lext you see the same action twice. Notice that for instance in Index of actions they do not expand (this is just a table with links).
Maybe an alternative could be to add e.g. at the end of the bias <https://plumed.github.io/doc-isdb/user-doc/html/_bias.html> page a sentence such as
Notice that other biases are available in the following modules:
- PLUMED-ISDB
Here PLUMED-ISDB could have a link directly to isdb-bias <https://plumed.github.io/doc-isdb/user-doc/html/_i_s_d_b_bias.html>
Could this make sense?
—
You are receiving this because you commented.
Reply to this email directly, view it on GitHub <#253 (comment)>, or mute the thread <https://github.com/notifications/unsubscribe-auth/AEXl9qeCd7oeU75ThlO0w8JT7LMKWvRdks5sPi8EgaJpZM4OH7G4>.
|
|
Yes this I understand, still to me it is confusing that they appear twice... I wanted to check the pdf manual (to see if variables appear twice) but I now realize that in this manual the section |
|
I should have fixed it now
… On 19 Jul 2017, at 18:45, Giovanni ***@***.***> wrote:
Yes this I understand, still to me it is confusing that they appear twice...
I wanted to check the pdf manual (to see if variables appear twice) but I now realize that in this manual <https://plumed.github.io/doc-isdb/user-doc/html/index.html> the section @PDFMANUAL@ is missing. Is this on purpose (i.e. you disabled it) or maybe there is some problem in the script?
—
You are receiving this because you commented.
Reply to this email directly, view it on GitHub <#253 (comment)>, or mute the thread <https://github.com/notifications/unsubscribe-auth/AEXl9lBi4HZjzNSiw_etMw5MQb3YslErks5sPjK5gaJpZM4OH7G4>.
|
|
I am also fixing for VERSION, this should be the last one
… On 19 Jul 2017, at 18:52, Carlo Camilloni ***@***.***> wrote:
I should have fixed it now
> On 19 Jul 2017, at 18:45, Giovanni ***@***.*** ***@***.***>> wrote:
>
> Yes this I understand, still to me it is confusing that they appear twice...
>
> I wanted to check the pdf manual (to see if variables appear twice) but I now realize that in this manual <https://plumed.github.io/doc-isdb/user-doc/html/index.html> the section @PDFMANUAL@ is missing. Is this on purpose (i.e. you disabled it) or maybe there is some problem in the script?
>
> —
> You are receiving this because you commented.
> Reply to this email directly, view it on GitHub <#253 (comment)>, or mute the thread <https://github.com/notifications/unsubscribe-auth/AEXl9lBi4HZjzNSiw_etMw5MQb3YslErks5sPjK5gaJpZM4OH7G4>.
>
|
|
I see, actually the |
|
I agree |
|
I tried the modified extract script by Carlo on the manual of my code and it seems to work exactly as it should. I would agree that the extract script is not very user-friendly, nor is it easy to understand how it work. I noticed one issue, if I have a command line tools that is in the category VES_TOOLS it goes correctly into both sections of the manual (VES_TOOLS and TOOLS). However, there is a plumedcheck failure: [global_check] (error) :plmd_unregistered_action: action ves_md_linearexpansion at ves/MD_LinearExpansionPES.cpp:53 is not registered So I guess the plumedcheck script has to be modified to reflect that changes in the manual construction. |
|
@valsson ok that should be easy to fix. @carlocamilloni can you transplant the script on the v2.4 branch? I don't know if you plan to merge the whole isdb branch now. In case not, you can just copy the new script. (notice though that there is still some issue with the description of the PDF manual). I reiterate that I am not fully satisfied with the duplication of the keywords and I would like to find a solution where in one of the two places there are just links, but I agree that this is a good starting point. I can try to refine the script later. As a reminder, if anyone (@plumed/all) wants to play with manual generating it on Travis-CI, you can just force push on |
|
PDFmanual is now fixed, yes I can copy the extract script to v2.4. |
|
about the double listing now it is actually not too bad, if you select METAINFERENCE in the bias section it automatically moves you to the isdb section |
|
I actually like the repetition and I think it can be useful to have in a single page
colvars, biases, and functions of all modules, so people can quickly look across different modules
and have ideas about how to combine CVs from different areas. On the other side,
I think we need for each module a separate page that shows its functionalities.
This is what we have been asked when submitting the paper of the isdb module and, more
important, it gives a better visibility to other people contribution.
… On Jul 21, 2017, at 12:18, Carlo Camilloni ***@***.***> wrote:
about the double listing now it is actually not too bad, if you select METAINFERENCE in the bias section it automatically moves you to the isdb section
—
You are receiving this because you are on a team that was mentioned.
Reply to this email directly, view it on GitHub, or mute the thread.
|
|
I just pushed on branch v2.4 a version where actions from separate modules appear at the end of the list in a separate table. @valsson can you check if this works well also for the VES module? It should be sufficient to merge v2.4 in. |
|
I merged it and it works but personally while I like the table I would prefer to have the keywords also in the left menu, just because that is the only thing I look at. @maxbonomi ? |
|
As an alternative, would it be ok to remove them from the left menu of PLUMED-ISDB so that they appear only in the left menu of the bias/colvar/function part? That's super easy (just swapping ref and subpage in the generation of the manual) |
|
The point is that I don't share your dislike for the duplication of the keywords in the left menu ;-) I mean I don't see why there should be a table but then only some actions are on the left and some are not. It is clear that if something appear twice is because it can belong to more than one category |
|
I tested the new script on the manual for the VES module and it seems to work fine. I also agree with @carlocamilloni regarding the duplication of the keywords in the left menu, to me it looks better. What about tutorial, would it be possible to extend this scheme to tutorials? I have tutorials inside the tutorials folder that are called ves_aaa that I would like to have inside the module subpage. What about if there are tutorials called pippo_aaa they would go to a list called PIPPO_TUTORIALS.list which could be used inside module page? Would this be possible? |
|
I will add one more thought. Shall we group all the modules in a page
'Contributed Modules' ?
As people will start contributing modules, the list on the left menu will
get longer and longer (and kind of ugly). I think it would be better just
to have one line on the left that expands into all the contributed modules.
The main page for 'Contributed Modules' would report a brief description of
each module and the authors.
Max
Sent from my Nexus. Please excuse typos and brevity.
…On Jul 24, 2017 10:56, "Omar Valsson" ***@***.***> wrote:
I tested the new script on the manual for the VES module and it seems to
work fine. I also agree with @carlocamilloni
<https://github.com/carlocamilloni> regarding the duplication of the
keywords in the left menu, to me it looks better.
What about tutorial, would it be possible to extend this scheme to
tutorials? I have tutorials inside the tutorials folder that are called
ves_aaa that I would like to have inside the module subpage. What about if
there are tutorials called pippo_aaa they would go to a list called
PIPPO_TUTORIALS.list which could be used inside module page? Would this be
possible?
—
You are receiving this because you were mentioned.
Reply to this email directly, view it on GitHub
<#253 (comment)>, or mute
the thread
<https://github.com/notifications/unsubscribe-auth/ACj-wTuRucXd0d2UOzNgl9uxLWbzRpYbks5sRFw6gaJpZM4OH7G4>
.
|
|
Yes I agree with Max on collecting modules together
…Sent from my iPhone
Il giorno 24 lug 2017, alle ore 14:12, Massimiliano Bonomi ***@***.***> ha scritto:
I will add one more thought. Shall we group all the modules in a page
'Contributed Modules' ?
As people will start contributing modules, the list on the left menu will
get longer and longer (and kind of ugly). I think it would be better just
to have one line on the left that expands into all the contributed modules.
The main page for 'Contributed Modules' would report a brief description of
each module and the authors.
Max
Sent from my Nexus. Please excuse typos and brevity.
On Jul 24, 2017 10:56, "Omar Valsson" ***@***.***> wrote:
> I tested the new script on the manual for the VES module and it seems to
> work fine. I also agree with @carlocamilloni
> <https://github.com/carlocamilloni> regarding the duplication of the
> keywords in the left menu, to me it looks better.
>
> What about tutorial, would it be possible to extend this scheme to
> tutorials? I have tutorials inside the tutorials folder that are called
> ves_aaa that I would like to have inside the module subpage. What about if
> there are tutorials called pippo_aaa they would go to a list called
> PIPPO_TUTORIALS.list which could be used inside module page? Would this be
> possible?
>
> —
> You are receiving this because you were mentioned.
> Reply to this email directly, view it on GitHub
> <#253 (comment)>, or mute
> the thread
> <https://github.com/notifications/unsubscribe-auth/ACj-wTuRucXd0d2UOzNgl9uxLWbzRpYbks5sRFw6gaJpZM4OH7G4>
> .
>
—
You are receiving this because you were mentioned.
Reply to this email directly, view it on GitHub, or mute the thread.
|
|
about the tutorials @valsson yes I think we should also include the tutorials in the module, it should be easy |
|
I checked the updated scripts and it seems to work fine. However, instead
of xxx-yyy.txt why not use the convention xxx_yyy.txt? This would be
consistent with how the actions are labelled (e.g. XXX_COLVAR).
On 25 July 2017 at 12:23:42, Carlo Camilloni (notifications@github.com) wrote:
@valsson <https://github.com/valsson> could you check the new changes
related to tutorials? commit 6a703be
<6a703be>
Tutorials related to modules should be places in tutorials/others and named
xxx-yyy.txt where xxx is the module name i.e. isdb-1.txt
—
You are receiving this because you were mentioned.
Reply to this email directly, view it on GitHub
<#253 (comment)>, or mute
the thread
<https://github.com/notifications/unsubscribe-auth/AFopLsEg4UyZB1L7cD00wBrWG6RpFIIgks5sRcItgaJpZM4OH7G4>
.
|
|
You are right, the only reason is that all other tutorials are named in this way.
… On 25 Jul 2017, at 13:41, Omar Valsson ***@***.***> wrote:
I checked the updated scripts and it seems to work fine. However, instead
of xxx-yyy.txt why not use the convention xxx_yyy.txt? This would be
consistent with how the actions are labelled (e.g. XXX_COLVAR).
On 25 July 2017 at 12:23:42, Carlo Camilloni ***@***.***)
wrote:
@valsson <https://github.com/valsson> could you check the new changes
related to tutorials? commit 6a703be
<6a703be>
Tutorials related to modules should be places in tutorials/others and named
xxx-yyy.txt where xxx is the module name i.e. isdb-1.txt
—
You are receiving this because you were mentioned.
Reply to this email directly, view it on GitHub
<#253 (comment)>, or mute
the thread
<https://github.com/notifications/unsubscribe-auth/AFopLsEg4UyZB1L7cD00wBrWG6RpFIIgks5sRcItgaJpZM4OH7G4>
.
—
You are receiving this because you were mentioned.
Reply to this email directly, view it on GitHub <#253 (comment)>, or mute the thread <https://github.com/notifications/unsubscribe-auth/AEXl9mMnvyPEj6Xo401J9eEKtqed1-y4ks5sRdSBgaJpZM4OH7G4>.
|
|
@valsson could you check if the new addition of a single page where all module are collected works for your version? You can look at the ISDB branch for reference. |
|
Carlo, can we just add to the page "Additional Modules” a brief, one line description of the ISDB module?
… On Aug 2, 2017, at 15:19, Carlo Camilloni ***@***.***> wrote:
@valsson could you check if the new addition of a single page where all module are collected works for your version? You can look at the ISDB branch for reference.
—
You are receiving this because you were mentioned.
Reply to this email directly, view it on GitHub, or mute the thread.
|
|
Maybe with authors and a reference (where available)
… On Aug 2, 2017, at 15:25, Massimiliano Bonomi ***@***.***> wrote:
Carlo, can we just add to the page "Additional Modules” a brief, one line description of the ISDB module?
> On Aug 2, 2017, at 15:19, Carlo Camilloni ***@***.***> wrote:
>
> @valsson could you check if the new addition of a single page where all module are collected works for your version? You can look at the ISDB branch for reference.
>
> —
> You are receiving this because you were mentioned.
> Reply to this email directly, view it on GitHub, or mute the thread.
>
|
|
I am also wondering if in the global bias / cv page we can substitute:
(from ISDB module)
with (from PLUMED-ISDB) where PLUMED-ISDB matches the name listed in the Additional Modules
and it is a link to the main module page
Max
… On Aug 2, 2017, at 15:29, Massimiliano Bonomi ***@***.***> wrote:
Maybe with authors and a reference (where available)
> On Aug 2, 2017, at 15:25, Massimiliano Bonomi ***@***.***> wrote:
>
> Carlo, can we just add to the page "Additional Modules” a brief, one line description of the ISDB module?
>
>> On Aug 2, 2017, at 15:19, Carlo Camilloni ***@***.***> wrote:
>>
>> @valsson could you check if the new addition of a single page where all module are collected works for your version? You can look at the ISDB branch for reference.
>>
>> —
>> You are receiving this because you were mentioned.
>> Reply to this email directly, view it on GitHub, or mute the thread.
>>
>
|
|
I think that the substitution with from PLUMED-ISDB should be made. |
|
Yes I was also thinking about it but I haven’t yet found a not too dirty way of doing it
… On 2 Aug 2017, at 15:25, Massimiliano Bonomi ***@***.***> wrote:
Carlo, can we just add to the page "Additional Modules” a brief, one line description of the ISDB module?
> On Aug 2, 2017, at 15:19, Carlo Camilloni ***@***.***> wrote:
>
> @valsson could you check if the new addition of a single page where all module are collected works for your version? You can look at the ISDB branch for reference.
>
> —
> You are receiving this because you were mentioned.
> Reply to this email directly, view it on GitHub, or mute the thread.
>
—
You are receiving this because you were mentioned.
Reply to this email directly, view it on GitHub <#253 (comment)>, or mute the thread <https://github.com/notifications/unsubscribe-auth/AEXl9oXfCFKAHQpasKfbbb-53KkX8BS2ks5sUHjhgaJpZM4OH7G4>.
|
|
Done, this can be added using these lines in the XXX.md file (e.g. ISDB.md) |
|
very nice!
… On Aug 2, 2017, at 16:50, Carlo Camilloni ***@***.***> wrote:
Done, this can be added using these lines in the XXX.md file (e.g. ISDB.md)
—
You are receiving this because you were mentioned.
Reply to this email directly, view it on GitHub, or mute the thread.
|
|
now instead of (from ISDB) we have the link to the module page
|
|
I think it is better this way!
… On Aug 2, 2017, at 17:10, Carlo Camilloni ***@***.***> wrote:
now instead of (from ISDB) we have the link to the module page
I am also wondering if in the global bias / cv page we can substitute:
(from ISDB module)
with (from PLUMED-ISDB) where PLUMED-ISDB matches the name listed in the Additional Modules
and it is a link to the main module page
—
You are receiving this because you were mentioned.
Reply to this email directly, view it on GitHub, or mute the thread.
|
|
@carlocamilloni I tried the new script and it works pretty well. One thing is that now one has to add by hand the XXXXPP.md file to the list in the go-doxygen script, and this is something that is easy to forget. Is there a way to do this in an automatic way, for example by copying the XXXXPP.md file to the automatic folder in the extract script, then there is no need to add it to the list in go-doxygen. Then everything is done in an automatic fashion. Another thing is that the plumedcheck script has to be modified so there is not a failure for command line tools that are documented with XXXX_TOOLS, see my comment above. |
|
All issues should be addressed now |
I open an issue related to manual refactoring so that we can public comment on it.
The goal is to end up with a manual where there is a sub menu for each contributed module including:
The plan is to incorporate many ideas from how @valsson did the manual for his VES code (manual here).
In particular, we might define some rule such that:
@PIPPO_BIAS@to be replaced with the proper tables during manual generationThe text was updated successfully, but these errors were encountered: