Differences

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

--- developers:generate_doc [2017/08/18 08:56] – [The ABINIT HTML doc] Xavier Gonze
+++ developers:generate_doc [2019/10/24 00:42] (current) – removed Matteo Giantomassi
@@ Line 1: / Line 1: @@
-====== The ABINIT HTML doc ======
-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.
-Usage : <color blue>python generate_doc.py [-h|--help]</color>\\
-(No options are allowed at present, except the help ones)
-This script :
-  - Reads information from: (i) a set of YAML files, (ii) a bibtex file, (iii) input files contained in tests/*/Input. Files (i) and (ii) are contained in subdirectories */origin_files.
-  - Performs some checks.
-  - Establishes intermediate dictionaries and databases.
-  - Expands special strings, of the form %%"[[tag]]"%%, to create HTML links.
-  - Creates the needed HMTL files (all contained in different subdirectories */generated_files).
-The expansion of special strings is documented in [[developers:link_shortcuts]].
-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 visualize correctly TeX formulas, see also [[developers:link_shortcuts]].
-===== Input variables : How to add/modify ? =====
-Edit the file ~abinit/doc/input_variables/origin_files/abinit_vars.yml, thanks to the GUI Abivars.jar, with the command
-<color blue>java -jar Abivars.jar</color>
-A window should open, and you can fill the requested information ...\\
-To add a new variable, click on "Edit" (upper right) then click on "Add new variable".\\
-Note that input variables for the executables other than the main abinit (e.g. anaddb, aim, optic) are
-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 (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.
-===== Bibliographic reference : how to add/modify ? =====
-Edit the file ~abinit/doc/bibliography/origin_files/abiref.bib with your preferred browser. It is a standard bibtex file.
-Note that the ID must be of the form "FirstauthornameYEAR", e.g. "Amadon2008" (start with an uppercase letter,
-then lower case, then four-digit year). Possibly, a letter might be added in case of ambiguity: e.g. there exists also
-"Amadon2008a" .\\
-Then, build the HTML using generate_doc.py.
-===== Topics : how to add/modify ? =====
-The topic HTML files are "assembled" by generate_doc.py from different sources.\\
-The high-level information is contained in ~abinit/doc/topics/origin_files/topic_NAME.yml,
-where NAME is the name of the topic. The first section ("introduction") is also found in this file,
-as well as the information on lessons of the tutorial that are relevant for this topic. The "text" content of
-the "introduction" section is in plain HTML.\\
-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]], as well as [[developers:topics_and_tribes]], while the list of relevant input files
-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]].
-Note the file default_topic.yml, whose components are used in case they are not specified explicitly
-in the more specific file topic_NAME.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.
-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 ised
-  * 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.
-===== Lessons of the tutorial : how to add/modify ? =====
-The major part of each lesson HTML file comes from ~abinit/doc/topics/origin_files/lesson_NAME.yml,
-although selected high-level information (name, keyword, author and subtitle)
-is contained in ~abinit/doc/topics/origin_files/lessons.yml. Note the last section of the latter file,
-that gives a default value for each component of a lesson file that would not have been specified in
-either lesson_NAME.yml or the specific section of lessons.yml .\\
-The content of ~abinit/doc/topics/origin_files/lesson_NAME.yml is either :
-  * an "intro" section and a "body" section,
-  * or (this is preferred), an "intro" section and a list of sections, each having a "title" and a "body".
-In the latter case, a table of content is automatically generated by generate_doc.py .
-The latter structure can be seen in lesson_dmft.yml .\\
-The "text" content of these section is in plain HTML.
-Note that the indentation is important in YAML.
-The "text" lines in lesson_NAME.yml must be indented by at least two blanks.\\
-In order to add a new lesson, introduce a new section in lessons.yml, and create a new
-~abinit/doc/topics/origin_files/lesson_NAME.yml .
-Then, build the HTML using generate_doc.py.
-===== Help files : how to add/modify ? =====
-The structuration for help files is very similar to the one for the lessons of the tutorial.
-The major part of comes from ~abinit/doc/users/origin_files/help_NAME.yml,
-although selected high-level information (name, keyword, author and subtitle)
-is contained in ~abinit/doc/topics/origin_files/helps.yml.
-Do not forget to build the HTML using generate_doc.py.
-===== Theory documents : how to add/modify ? =====
-The structuration for theory documents is very similar to the one for the lessons of the tutorial.
-The major part of comes from ~abinit/doc/users/origin_files/theorydoc_NAME.yml,
-although selected high-level information (name, keyword, author and subtitle)
-is contained in ~abinit/doc/topics/origin_files/theorydocs.yml.
-Do not forget to build the HTML using generate_doc.py.