Tips for ABINIT users and developers

User Tools

Site Tools

Trace:
beauty:2018

Differences

This shows you the differences between two versions of the page.

Link to this comparison view

Both sides previous revisionPrevious revision
Next revision		Previous revision
beauty:2018 [2018/06/02 17:23] – [In practice : branching/merging] Xavier Gonzebeauty:2018 [2018/06/03 23:11] (current) – [What should be done ?] Xavier Gonze
Line 12: Line 12:
 ==== In practice : branching/merging  ==== ==== In practice : branching/merging  ====
  
-I expect your contribution to be in a branch named "user_name"/beauty.+I expect [[beauty:2018:taskvolunteers|your contributions]] to be in a branch named "user_name"/beauty.
 So, please start from your develop branch (v8.9.3 of ABINIT), branch your own "beauty" branch, upgrade it to the latest trunk/develop, work in it, So, please start from your develop branch (v8.9.3 of ABINIT), branch your own "beauty" branch, upgrade it to the latest trunk/develop, work in it,
 then issue a merge request (using Gitlab) from "user_name"/beauty to trunk/develop. then issue a merge request (using Gitlab) from "user_name"/beauty to trunk/develop.
  
-So, issue +Explicitly, issue 
  
   - git checkout develop   - git checkout develop
Line 22: Line 22:
   - git checkout beauty   - git checkout beauty
   - git merge remotes/trunk/develop (or your method to sync with the trunk)   - git merge remotes/trunk/develop (or your method to sync with the trunk)
-  then beautify the code, then issue the proper merge request to trunk/develop.+  then beautify the code, then issue the proper merge request to trunk/develop, then mention in the [[beauty:2018:tasks|task list]] that you have done the job !
  
 ==== What should be done ? ==== ==== What should be done ? ====
Line 28: Line 28:
 This beautification will be focused on the documentation. Indeed, as a response to the recommendations made at the last developer workshop, in Frejus May 2017, "topics" have been introduced and lead to completion, a centralized bibliography database has been set up, and a new global infrastructure based on mkdocs (and markdown) has been established. However: This beautification will be focused on the documentation. Indeed, as a response to the recommendations made at the last developer workshop, in Frejus May 2017, "topics" have been introduced and lead to completion, a centralized bibliography database has been set up, and a new global infrastructure based on mkdocs (and markdown) has been established. However:
  
-  * A. it is likely that there are still isolated bibliographical references in the descriptions of input variables or lessons of the tutorial (or other files), to be ported inside the bibliography database, see https://docs.abinit.org/developers/abimkdocs/#how-to-add-a-bibliographic-reference +  * A. There are still MANY isolated bibliographical references in the descriptions of input variables or lessons of the tutorial (or other files), [[https://docs.abinit.org/developers/abimkdocs/#how-to-add-a-bibliographic-reference|to be ported inside the bibliography database]]. 
-  * B. Equations might still be in "text" style, while they should be now in "LaTex" style (interpreted using MathJax, see https://docs.abinit.org/developers/markdown/#mathjax) +  * B. Many line breaks have disappeared in the input variable descriptions (so, one big paragraph appears instead of several paragraphs) 
-  * C. specific improvements of lessons of the tutorials and other files could be made, thanks to the new mkdocs infrastructure. +  * C. Equations might still be in "text" style, while [[https://docs.abinit.org/developers/markdown/#mathjax|they should be now in "LaTex" style]] (interpreted using MathJax) 
-  * D. it remains to be checked that no inadvertent deterioration of the documentation has occurred. +  * D. Specific improvements of lessons of the tutorials and other files could be made, thanks to the new mkdocs infrastructure. 
-  * E. one might also check the correctness of links and other information (like the coherence between the sections of output files pasted in the text, and the output files themselves, available from the links)+  * E. It remains to be checked that no inadvertent deterioration of the documentation has occurred. 
 +  * F. One might also check the correctness of links and other information (like the coherence between the sections of output files pasted in the text, and the output files themselves, available from the links) 
 +   
 +As an indication, each contributor might have to dedicate about three hours to this work (including, if not yet done, reading the mkdocs documentation and possibly training a bit with the mksite script). By the way, suggestions for improvements of the mkdocs infrastructure is also welcome, see the dedicated page. 
  
-It is proposed that a concerted beautification operation will be done Monday 4 June - Wednesday 14 June 2018. Every contributor will be given a set of files that s/he should read and possibly correct.   
-As an indication, each contributor might have to dedicate about three hours to this work (including, if not yet done, reading the mkdocs documentation and possibly training a bit with the mksite script). More information on the operation will be given in later sections. By the way, suggestions for improvements of the mkdocs infrastructure is also welcome, see the dedicated page.  
- 
-The first phase will be to collect the name of volunteers, see [[beauty:2018:taskvolunteers|List of volunteers and attributions]] ... 
- 
-==== Sets of files to be examined and improved ==== 
- 
-  - Input variables contained in abimkdocs, see the files variables_abinit.py, variables_aim.py, variables_anaddb.py, variables_optic.py. Of course, the file variables_abinit.py is too big to be taken by one developer. In this respect, the input variables of ABINIT will be distributed according to their "varset" ("Basic", "Bethe-Salpeter", Developers", "DMFT", ... see the list e.g. in the leftmost column of the input variables Web pages, as an example, see https://docs.abinit.org/variables/basic/#accuracy). There are 17 such "varsets". Counting 17 varsets for ABINIT + ANADDB + AIM + OPTIC make for 20 sets of input variables. 
-  - Lessons of the Tutorial : 38 *.md files contained in doc/tutorial ; 
-  - Theory  : 8 *.md files contained in doc/theory ; 
- 
-So, the work will consists in the beautification of 46 *.md files, 17 varsets and 3 remaining variables*.py files. To summarize, 66 tasks to be distributed.  
- 
-Moreover, as the addition of new tutorial and documentation is facilitated with respect to the previous procedure,  
-adding new tutorials or documentation for new executables might also be done by volunteers, or any filling of holes in the documentation. 
-For example, multibinit and tdep documentation is missing (but is underway for multibinit !), the tutorial on spin/spin-orbit  
-could be extended, the tutorial on source_code should be rewritten from scratch... 
 ==== When an isolated bibliographical reference is found  ==== ==== When an isolated bibliographical reference is found  ====
  
 Check first whether it exists already in the bibliographical database Check first whether it exists already in the bibliographical database
 (file doc/abiref.bib), and if so, simply refer to it using a "cite" wikilink. (file doc/abiref.bib), and if so, simply refer to it using a "cite" wikilink.
-Otherwise, introduce the adequate bibtex information, following +Otherwise, 
-[[https://docs.abinit.org/developers/abimkdocs/#how-to-add-a-bibliographic-reference]]+[[https://docs.abinit.org/developers/abimkdocs/#how-to-add-a-bibliographic-reference|introduce the adequate bibtex information]]
  
 ==== I have not yet familiarized myself with abimkdocs / markdown  ==== ==== I have not yet familiarized myself with abimkdocs / markdown  ====
Line 68: Line 54:
 Training might be another 15 minutes (e.g. starting the server with ''./mksite.py serve --dirtyreload'', Training might be another 15 minutes (e.g. starting the server with ''./mksite.py serve --dirtyreload'',
 then trying to make some fake modifications). then trying to make some fake modifications).
 +
 +
 +==== Sets of files that will be examined and improved ====
 +
 +Most of the following files have been assigned to contributors :
 +  - Input variables contained in abimkdocs, see the files variables_abinit.py, variables_aim.py, variables_anaddb.py, variables_optic.py. Of course, the file variables_abinit.py is too big to be taken by one developer. In this respect, the input variables of ABINIT will be distributed according to their "varset" ("Basic", "Bethe-Salpeter", Developers", "DMFT", ... see the list e.g. in the leftmost column of the input variables Web pages, as an example, see https://docs.abinit.org/variables/basic/#accuracy). There are 17 such "varsets". Counting 17 varsets for ABINIT + ANADDB + AIM + OPTIC make for 20 sets of input variables.
 +  - Lessons of the Tutorial : 38 *.md files contained in doc/tutorial ;
 +  - Theory  : 8 *.md files contained in doc/theory ;
 +
 +So, the work will consists in the beautification of 46 *.md files, 17 varsets and 3 remaining variables*.py files. To summarize, 66 tasks to be distributed. 
 +
 +Moreover, as the addition of new tutorial and documentation is facilitated with respect to the previous procedure, 
 +adding new tutorials or documentation for new executables might also be done by volunteers, or any filling of holes in the documentation.
 +For example, multibinit and tdep documentation is missing (but is underway for multibinit !), the tutorial on spin/spin-orbit 
 +could be extended, the tutorial on source_code should be rewritten from scratch...
beauty/2018.1527953027.txt.gz · Last modified: 2018/06/02 17:23 by Xavier Gonze