.. _after-build:

Document Compilation
--------------------

Once a configuration file has been created describing the document to be built and how to build it, the document can be compiled using the ``pygacity build`` command.  This command reads the configuration file, generates the necessary LaTeX code, and compiles the document.  During this process, if any python code is included in the document using pythontex, it will be executed and the results will be incorporated into the final document.

For a configuration file ``my_config.yaml``, the command to build the document is:

.. code-block:: bash

    pygacity build my_config.yaml

This will produce the final document in PDF format in the output directory specified in the configuration file.

``--bundle-size`` and ``--two-sided``
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

``pygacity build`` also accepts two options for generating print-ready bundle PDFs that
combine multiple exam copies into a single file:

.. code-block:: bash

    pygacity build my_config.yaml --bundle-size 15 --two-sided

``--bundle-size N`` (default: ``10``) groups the generated student exam PDFs into bundles
of at most *N* copies and writes one bundle PDF per group alongside the individual exam
files.  Pass ``--bundle-size 0`` to disable bundling entirely.

``--two-sided`` (default: off) pads each exam to an even page count by appending a blank
page whenever an exam has an odd number of pages.  This guarantees that the first page of
every exam in a bundle falls on a right-hand sheet when the bundle is printed double-sided.
Use ``--no-two-sided`` to explicitly disable it.  

By default, if an output directory is not specified, the document will be generated in a subdictory named ``build/`` in the current working directory.  By default, ``pygacity`` generates several outputs in the build directory.  For example, if ``job-name`` is set to ``Assignment``, the following files will be generated:

.. code-block:: text

    build/
    ├── Assignment.pdf        # Final document
    ├── Assignment_soln.pdf   # Final document with solutions
    ├── buildfiles.zip        # Files created by the build process
    ├── .cache/               # Cache directory (may be empty)
    │   └── ...               # Cached files (if any)
    ├── solnbuildfiles.zip    # Files created by the solution build process
    └── tex_artifacts.zip     # Any LaTeX code files generated by pygacity

When building multiple versions of a document (i.e., when ``copies`` is greater than 1), each version will be generated with a unique serial number appended to the job name.  For example, if ``job-name`` is set to ``ExamI`` and ``copies`` is set to 3 (and ``seed`` is set to ``12345``), the following files will be generated:

.. code-block:: text

    build
    ├── answerset_buildfiles.zip
    ├── answerset.pdf
    ├── buildfiles.zip
    ├── .cache
    │   ├── answers-11364882.pkl
    │   ├── answers-50082762.pkl
    │   └── answers-65917772.pkl
    ├── ExamI-11364882.pdf
    ├── ExamI-11364882_soln.pdf
    ├── ExamI-50082762.pdf
    ├── ExamI-50082762_soln.pdf
    ├── ExamI-65917772.pdf
    ├── ExamI-65917772_soln.pdf
    ├── ExamI-bundle-1.pdf
    ├── solnbuildfiles.zip
    └── tex_artifacts.zip

Note the three unique exam versions and their accompanying solution documents, each with a unique serial number.  Note also ``answerset.pdf``, which contains all of the answers for all versions of the exam in one document for easy reference, and ``ExamI-bundle-1.pdf``, which combines all three student exams into a single print-ready PDF (all three fit in one bundle with the default bundle size of 10).  The cached answer files in the ``.cache/`` directory store the generated answers for each serial in case a new answer set needs to be regenerated.

When ``build.serial-hex`` is ``true``, serial numbers appear as zero-padded hexadecimal strings in all filenames (e.g. ``ExamI-00ad6a12.pdf`` instead of ``ExamI-11364882.pdf``).  The width of the hex string is controlled by ``build.serial-hex-digits`` (default: ``8``).