Library usage
=============

Understanding PyLaTeX
---------------------
PyLaTeX is structured around two main tasks: Generating LaTeX code, and
compiling LaTeX documents. The package is flexible, and can either work with
your pre-existing code or generate new code with its system of classes.  In
turn, LaTeX code can be used to generate a document, or can be exported as-is.

The Classes
-----------
PyLaTeX uses a set of classes to turn LaTeX document generation into a set of
pythonic components. For example, a `~.Document` might be comprised of
`~.Section` objects, which in turn might have `~.List` objects, `~.Figure`
objects, or custom `~.Command` objects.

Classes can be part of a single document, or can act as pieces on their own.
With the `~.LatexObject.dumps` method, most classes can return their
LaTeX-formatted code, and with the `~.LatexObject.generate_tex` method, this
code can be written to a file.

Containers / Documents
~~~~~~~~~~~~~~~~~~~~~~
A `~.Container` is an object that groups other LaTeX classes. Containers
function like lists; they can be indexed and appended to.

One of the most important container classes is the `~.Document` class.
Documents create a full LaTeX document that can create a PDF file with
`~.generate_pdf` . Unless you are only generating LaTeX snippets, you will
likely want to enclose your code inside a Document.

Additionally, a number of `~pylatex.section` containers are available, which
correspond to the standard ``\section`` commands of LaTeX. As with documents,
these can be appended to. A `~.Section` can further include a `~.Subsection` or
a `~.Subsubsection` object.

Tables, Images, Math, etc.
~~~~~~~~~~~~~~~~~~~~~~~~~~
PyLaTeX has a number of classes that are useful in generating
difficult-to-format LaTeX code. See the API documentation and code examples for
information on a specific environment.

Commands, Options, and Arguments
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Although PyLaTeX has implemented many useful commands, it is easy to create a
custom command with the `~.Command` class.  Commands can be supplied with
``{}`` arguments or ``[]`` options, with either a single option as a string, or
multiple options in a list.

Additionally, Options and Arguments can be placed in an `~.Options` object or a
`~.Arguments` object.


Formatting Strings
~~~~~~~~~~~~~~~~~~
A number of functions are available in `~.utils` that are helpful in formatting
text. For example, the functions `~.bold` and `~.italic` exist to format text
appropriately.


Extending PyLaTeX
-----------------
Because of all the base classes supplied by PyLaTeX, it is very easy to extend
its support in LaTeX features. Just pick one of the existing (base) classes
that fits best and extend that with the needed functionality.

All LaTeX objects come from `~.LatexObject` , but it is probably more useful to
extend one of the other base subclasses, like `~.Environment` or
`~.CommandBase`. Consult the API documentation to see the variety of base
classes available for use.


Plain LaTeX Strings
-------------------
Although PyLaTeX contains classes and functions to make generating LaTeX
formatted text easy, at its core it is a nice wrapper around string
manipulations. This is why all of them also accept raw LaTeX strings. That way
you can just use regular LaTeX strings when something is not supported directly
by the library.

Unescaping Strings
~~~~~~~~~~~~~~~~~~
Using regular LaTeX strings may not be as simple as is seems though, because by
default almost all strings are escaped. This is done for security reasons and
to make sure valid LaTeX code will be generated at all times. However, there
are cases where raw LaTeX strings should just be used directly in the document.
This is why the `~.NoEscape` string type exists. This is just a subclass of
`str`, but it will not be escaped. One important thing to note about this class
is that appending a `~.NoEscape` type string to a regular string results in
a regular string, since one type has to be chosen and the most conservative
approach is taken.

Another way to make sure strings are not escaped is by setting the
`~.LatexObject.escape` attribute to `False` on the class that is the container
of the string. Keep in mind though that any strings that are added to that
object will not be escaped when doing this. So, only use this method for
objects that don't contain possibly unsafe strings.
