Documentation
The EnergyPlus documentation is written in LaTeX. This page contains some information for developers working with the documentation.
The documentation is located in a folder called doc/. Each pdf has its own subdirectory in that folder, although there are a header.tex and title.tex that are common to all document. Inside each subdirectory, there is a main file with the same name as the document that defines the document title, some pdf metadata, begins the document, and inputs supporting documents that each contain document chapters. These supporting documents can then import further supporting documents at the section, then subsection levels and so on. All graphics are stored at the document/media folder level.
There are many sources for help with LaTeX. Some key tips here:
- Units: The siunitx package should be used to specify standard units labels. e.g. \si{\volumeFlowRate} or \SI{5}{\celsius}. More info and some custom units for the EnergyPlus documentation are listed here.
- Quotation Marks: Enclose quotations with two leading backticks (accent grave) and two trailing apostrophes
``quoted text''. - Equations: Block equations should use the equation environment. Inline equations can use either
$or\(. Equations do not necessarily need labels, but they can be provided if the equation is to be referenced by number. If you do create labels, just use a descriptive label such as:\label{eq:calculating-probability-of-new-tool-album}. Using descriptive labels that are super clear will help ensure there are no label conflicts and it will also make referencing it in text very readable. - Figures: Figures should use the figure environment. Figures should be centered; I typically use
\centeringwithin the figure environment, but you can also use\begin{center}. For sizing the image, I usually use thewidth=0.6\textwidthtype of specification, but just use whatever you like to scale the image. Image files should be named descriptively, and if it makes sense you can even put them in a subfolder of the media folder. Captions should be placed under the graphics, but within the figure environment. - Tables: Tables should use a table environment, with the actual table contents placed in a tabular environment. Captions should be before the tabular environment so that it is over the table.
- Brackets: LaTeX interprets some characters in text mode instead of treating them as raw text. This causes some brackets to need to be handled specially. Here is a list of common brackets and how they should be handled in text mode:
\documentclass{report}
\usepackage{amssymb}
\renewcommand{\familydefault}{\sfdefault}
\begin{document}
\paragraph{Parentheses and Brackets in Text in \LaTeX}
\begin{itemize}
\item Parentheses (work well) just as they are in TeX.
\item Optionally, I have some [nice square] brackets.
\item Curly brackets get \{kinda\} funny, since they have to be escaped.
\item And look, I have some $<$of these$>$ brackets, but you need to enter $\mathbb{MATH MODE}$.
\item You need pipe symbols?
\begin{itemize}
\item |they get weird without math mode...|
\item $|$but back to normal inside math...$|$
\end{itemize}
\end{itemize}
\end{document}
...with the resulting rendered document:
There are many editors available for LaTeX with varying capabilities. Developers have recommended TeXStudio, TeXWorks, and TeXMaker, among others. You can also use Notepad or VI just as well. If you still need more help, check the interwebs.
Tips for building the documentation can be found on the Building EnergyPlus page.
If you don't want to build the PDFs locally, the continuous integration (CI) system automatically creates a set of documentation in PDF format for any pull request with commits. Click on the most recent CI results from an NREL-Bot with a label "x86_64-Linux-Ubuntu-14.04-gcc-4.8". Near the top of that page, click on the "Documentation" link to see the list of the PDFs.