Tips for ABINIT users and developers

User Tools

Site Tools

Trace:
developers:generate_doc

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
Last revisionBoth sides next revision
developers:generate_doc [2017/08/04 08:53] – [Input variables : How to add/modify ?] Xavier Gonzedevelopers:generate_doc [2018/05/26 22:43] – [The ABINIT HTML doc] Xavier Gonze
Line 1: Line 1:
-====== The ABINIT HTML doc ======+====== The ABINIT HTML doc (obsolete) ====== 
 + 
 +** THE INFORMATION ABOUT THE MANAGEMENT OF THE DOCUMENTATION HAS BEEN TRANSFERRED TO THE MAIN ABINIT SITE, AT  
 +https://docs.abinit.org/developers/abimkdocs **
  
 List of variables, lessons of the tutorial, help files, ABINIT topics, bibliography, theory documents are all important documentation files, posted on the Web, to help the users. The ~abinit/doc/generate_doc.py script generates most of these files by converting YAML files to HTML. List of variables, lessons of the tutorial, help files, ABINIT topics, bibliography, theory documents are all important documentation files, posted on the Web, to help the users. The ~abinit/doc/generate_doc.py script generates most of these files by converting YAML files to HTML.
Line 14: Line 17:
  
 The expansion of special strings is documented in [[developers:link_shortcuts]].  The expansion of special strings is documented in [[developers:link_shortcuts]]. 
-It can be used in all the YAML files mentioned below. +It can be used in all the YAML files mentioned below. For equations/formulas, 
 +[[http://docs.mathjax.org/en/latest/mathjax.html|Mathjax]] is activated, and allows 
 +to process and visualize LaTeX formulas, see also [[developers:link_shortcuts]].
  
 ===== Input variables : How to add/modify ? ===== ===== Input variables : How to add/modify ? =====
Line 28: Line 33:
 denoted "input_variable_name"@"executable", e.g. dipdip@anaddb (this allows to waive the ambiguity with the  dipdip input variable for the main abinit).\\ denoted "input_variable_name"@"executable", e.g. dipdip@anaddb (this allows to waive the ambiguity with the  dipdip input variable for the main abinit).\\
  
-After having edited the info related to one input variable (see the infos at [[developers:abivars.yml|Specs for abivars.yml]]), you must still SAVE THE ENTIRE FILE. Editing one input variable and saving the changes will go to some internal variable, and this is NOT saving your modifications in the YAML storage file. \\+After having edited the info related to one input variable (see the infos at [[developers:abivars.yml|Specs for abivars.yml]]), you must still SAVE THE ENTIRE FILE (click on "File" (upper right) then "Save"). Just editing one input variable and saving the changes will only go to some internal variable, and this is NOT saving your modifications in the YAML storage file. \\
 Then, build the HTML using generate_doc.py. Then, build the HTML using generate_doc.py.
- 
 ===== Bibliographic reference : how to add/modify ? ===== ===== Bibliographic reference : how to add/modify ? =====
  
Line 50: Line 54:
  
 At variance, the other sections of the topic_NAME.html are created from other sources. The list of input variables that are relevant to this topics is assembled from the information At variance, the other sections of the topic_NAME.html are created from other sources. The list of input variables that are relevant to this topics is assembled from the information
-given for these input variables, see [[#input variableshow_to_add_modify|Input variables : how_to_add_modify]], while the list of relevant input files +given for these input variables, see [[#input variableshow_to_add_modify|Input variables : how_to_add_modify]], as well as [[developers:topics_and_relevances]], while the list of relevant input files 
-is assembled from the information in each of these input files (see the line "topics"). The bibliography list is assembled+is assembled from the information in each of these input files (add a line "#%% topics = " in the last section of the input file.). The bibliography list is assembled
 from the references cited in the "introduction" section, that use [[developers:link_shortcuts|Shortcuts for Web links]]. from the references cited in the "introduction" section, that use [[developers:link_shortcuts|Shortcuts for Web links]].
  
Line 59: Line 63:
 The list of topics is found in the file ~abinit/doc/topics/origin_files/list_of_topics.yml . The list of topics is found in the file ~abinit/doc/topics/origin_files/list_of_topics.yml .
  
-Thus, if you want to a modify "topic" Web page, the "introduction" and "tutorial" sections as well as the name and some other high level info can be modified by editing ~abinit/doc/topics/origin_files/topic_NAME.yml, while you have to edit the relevant input variables and input files to modify the next sections. You can modify the bibliography section only through a modification of the "introduction" and "tutorial" sections. To add a new topic, add the name in list_of_topics.yml, and then create a corresponding topic_NAME.yml file.+Thus, if you want to a modify "topic" Web page, the "introduction" and "tutorial" sections as well as the name and some other high level info can be modified by editing ~abinit/doc/topics/origin_files/topic_NAME.yml, while you have to edit the relevant input variables and input files to modify the next sections. You can modify the bibliography section only through a modification of the "introduction" and "tutorial" sections.  
 + 
 +To add a new topic, add the name in list_of_topics.yml, and then create a corresponding topic_NAME.yml file. 
 +The different components are used by the script generate_doc.py as follows: 
 +  * name : must be the name of the topics, also used in the name of file (topic_name.yml) 
 +  * keyword : will be inserted in the HTML header to create the Web name of the HTML page, if the default header is used 
 +  * authors : will be inserted in the copyright, if the default copyright is used 
 +  * howto : will be inserted in the subtitle of the Web page "How to ... ?" if the default subtitle is used 
 +  * header : the HTML header (usually, take the default, that uses the component "keyword") 
 +  * title : the title that will be echoed in the HTML page 
 +  * subtitle : the subtitle (usually, take the default, that uses the component "howto") 
 +  * copyright : the copyright (usually, take the default, that uses the component "authors") 
 +  * links : list of links to other pages (usually, take the default) 
 +  * introduction : see above 
 +  * tutorials : see above 
 +  * end : final tags, take the default
  
 Then, build the HTML using generate_doc.py. Then, build the HTML using generate_doc.py.