Developers:Writing Documentation

From OctopusWiki

Jump to: navigation, search

This page contains guidelines for writing documentation. The current version is by no means definitive, all contributions are welcome. If you don't agree with something please say it, the mailing list or the meetings are the ideal places for that.


Contents

[edit]

General guidelines

The documentation for Octopus can be found in The Octopus Wiki. All contents, except the Reference Manual, should be written and edited there.

The main Documentation page is Documentation, this documentation is divided in several parts:

  • Manual: This is the main manual, aimed to final users of octopus.
  • Developers Manual: This manual (will) contains information for developers of octopus or people who wants to modify the code.
  • Tutorial
  • FAQ

There is also the complete wiki, that contains some information that can't be considered as part of some manual and the webpage.

[edit]

Structure

  • To organize hierarchically the manual the standard separator is a single colon (mediawiki's default), several separations can be used.
  • Manual pages should be sequential, this means, they must have an order with each page having a link to previous and next page. This is not yet implemented because we are far from having a definitive structure.
[edit]

Mediawiki's capabilities

Mediawiki (the engine that we use for our wiki) has some features that can make our work easier:

  • Templates: Templates are like macros in C. In the most simple form, when you call a template, the template replaces the arguments passed inside of a text and inserts it in the document. We use templates to ease the writing of documents, to have an uniform style and to have more flexibility to do changes in the documentation (we don't have to decide of specific format issues before writing). If you want to create or edit template check the templates help.
[edit]

Style templates

This are templates defined to remark different types of object inside the text. This way we separate semantics of implementation, using this templates is mandatory. Please add new styles as needed. If you don't like how the result of the template looks like, edit the template, do not apply the style directly to the text.

Characters like | and = are specially treated by templates, if you want to used them as text inside the template you have to put them between <nowiki></nowiki>.

[edit]
Text styles

These are commonly used inside of the text. Currently the actual formats that are applied to each style are not the best, but this can be changed later.


Text style How you type it How it looks
Emphasize {{emph|not}} not
Names, packages names, format names, etc. {{name|LAPACK}} LAPACK
File names in general {{file|inp}} inp
Directories use the same template but with a slash at the end {{file|status/}} status/
Names of files in the octopus installation (you have to specify files relative to prefix/) {{inst_file|share/octopus/}} PREFIX/share/octopus/
Operating system commands inside of the text {{command|rm -fr}} rm -fr
Operating system commands in a separated line (not displayed correctly here) {{command_line|rm -fr}} $ rm -fr
Units {{units|eV}} [eV]
Code, input file instructions, and values for input variables {{code|a b}} a b
Code line, same as above but when in a line (for large pieces of code just use <pre>) {{code_line|print*, "hello world"}} print*, "hello world"
Flag, when mentioned alone, it's here because is not clear how to treat them {{flag|--help}} --help
TO DO, marks that there is something missing (not printed) {{TODO| something}} TO DO something
[edit]
Constants
Text style How you type it How it looks
The name of our program {{octopus}} Octopus
Version of octopus covered by this manual {{octopus_version}} 3.0.1
Angstrom {{angstrom}} Å
Bohr, the atomic unit of lenght, there are different ways to abbreviate it, so use the template {{bohr}} b
Hartree, only the energy unit, same problem as bohr {{hartree}} Ha
Pipe, equivalent to <nowiki>|</nowiki> (optional) {{pipe}} |
Eq, equivalent to <nowiki>=</nowiki> (optional) {{eq}} =
[edit]
Refering Input Variables

To reference an Input value in the wiki, you must use the Variable template that will include a correct link to the online variable documentation. The syntax is {{Variable|Name|Section}}, where section is the main section where the variable belongs (capitalization is important).

For example {{Variable|CalculationMode|Generalities}} produces CalculationMode.

[edit]
Articles and books

To include publications use the article template. Here is an example (the title argument is optional): 

{{article
|title=octopus: a first-principles tool for excited electron-ion dynamics
|authors=M.A.L. Marques, Alberto Castro, George F. Bertsch, and Angel Rubio
|journal=Comput. Phys. Commun.
|volume=151
|pages=60-78
|year=2003
|url=http://www.sciencedirect.com/
|link=Science Direct
}}

and this is the result:

M.A.L. Marques, Alberto Castro, George F. Bertsch, and Angel Rubio, octopus: a first-principles tool for excited electron-ion dynamics, Comput. Phys. Commun. 151 60-78 (2003) Science Direct.

There is also a template for books, for example: 

*{{book
|title=Relativistic Quantum Mechanics
|author=Paul Strange
|publisher=Cambridge University Press
|year=1998
|isbn=0521565839
}}

gives

Relativistic Quantum Mechanics, Paul Strange, Cambridge University Press, (1998), ISBN: 0521565839

[edit]
Cites, references and footnotes

Thanks to Miguel we have the Cite.php system installed

References work like this:

  • Rember to use the article and book templates, in this example they are not used for clarity.
  • You add a cite with <ref> and </ref>:

<ref>Miller, E: "The Sun.", page 23. Academic Press, 2005</ref>[1]

  • If you want to cite multiple times the same reference you add the name tag:

<ref name="multiple">Remember that when you refer to the same footnote multiple times, the text from the first reference is used.</ref>[2]

  • To cite again: <ref name="multiple" />[2]
  • Then you put <references/> in the place where you want the references:
  1. ↑ Miller, E: "The Sun.", page 23. Academic Press, 2005
  2. ↑ 2.0 2.1 Remember that when you refer to the same footnote multiple times, the text from the first reference is used.
[edit]

Manual

This section contains specific information for the octopus manual.

[edit]

Namespace

The name of all pages of the manual must begin with "Manual:". In the link name you can remove the part before the colon.

[edit]

Footing

The footing of manual pages is generated by the Manual foot Template, to use it add the instruction {{manual_foot|prev=prev_page|next=next_page}} to the end of the page. Before having a definitive structure, you can omit the prev and next parameters.

[edit]

Documentation of Variables

  • The documentation of input variables must be included in the code, in the same file where the variable is read. In final releases all input variables should be documented.
  • The variables are classified in sections.
  • An online version of the input variables documentation is automatically generated and can be found here.
[edit]

Content guidelines

  • Examples input files should relay as much as possible in default variables, this makes the examples easier to understand, and also simpler to update.

For instance if in an example you are not focusing on the XC potential, just leave the default even if it's not your favorite. Also don't add extra convergence parameters if they are not necessary. This extra information will only confuse the reader.

[edit]

Printed version

Mediawiki is capable of producing printable version of the pages, to have a look of the printable version of a page, follow the link in the left menu. It is possible to specify that a certain content will not be included in the printed version, to do this enclose it between <span class=noprint> </span>. Save this only for navigation links or object that wouldn't make sense in a printed version.


Back to Manual
Back to Developers Manual

Retrieved from "http://www.tddft.org/programs/octopus/wiki/index.php/Developers:Writing_Documentation"
Personal tools