Project Documentation

Unofficial template for students in the BSc in Computer Science and Engineering undergraduate program at ISEL, designed for use in the Project and Seminar course documentation.

Important

Consult the official course page for the most up-to-date information, do not rely solely on this template

Table of Contents

• Features
• Goal
• Structure
• Instructions
  • Configure LaTeX environment in Intellij IDEA
  • Add a new subproject
  • Compile and build all subprojects
    • Manually
    • Automatically

Features

• ✅ Three LaTeX templates for required project documents:
  • Project Proposal: Initial document outlining the project objectives and plan.
  • Project Report: Final comprehensive report on the project's outcomes and findings.
  • Project Organization: Details the structure and management plan of the project.
• ✅ Automatic compilation and build: Ensures the most up-to-date version of the documents is always available without manual intervention.
• ✅ Basic examples of LaTeX usage: Includes tables, figures, references, equations, and other common LaTeX elements.
• ✅ Organized structure: Includes separate directories for LaTeX source files, generated PDFs, auxiliary files, and figures. This modular organization allows multiple team members to work on different sections or chapters simultaneously, minimizing potential conflicts and streamlining collaboration.
• ✅ Easy to add new documents: Features a simple configuration process for integrating additional components.
• ✅ Customizable LaTeX environment: Allows for the use of different configurations to tailor the setup to your needs.

Goal

As the template provides a ready-to-use LaTeX environment with a pre-designed layout and automatic compilation process, it allows you and your team to focus only on the content of the project documentation.

Note

This template provides a structure for managing and compiling LaTeX documents locally, but with the need to install necessary software. Alternatively, you can use Overleaf or any other online LaTeX editor, which allows you to work without installing any additional software. For that, place the LaTeX files in the online editor and compile them there.

Structure

Each subproject has the following structure, assuming no changes are made to the default configuration:

• src/: Contains the LaTeX source files:
  • main.tex: Main LaTeX file where the document is structured only;
  • bibliography.bib: Bibliography file where the references are stored;
  • sections/ or chapters/: Contains the sections or chapters of the document, depending on its size. This is where the content is written; usually, each section or chapter is a separate file, numbered in the order they appear in the document;
  • preamble.tex: Defines external packages, language, margins, fonts and new or redefined commands;
• out/: Contains the generated pdf file.
• auxil/: Contains the auxiliary files generated during the compilation process.
• figures/: Contains the figures used in the LaTeX source files.

With this structure, each team member can work on a different section or chapter of a document, minimizing potential conflicts. Unlike most templates that have everything in a single file, making simultaneous collaboration difficult, this template's modular design facilitates concurrent work on the same document.

Instructions

Configure LaTeX environment in Intellij IDEA

1. Install MikTeX;
   • Update MikTeX packages: MikTeX Console -> Updates -> Check for updates;
2. Install SumatraPDF viewer or any other pdf viewer of your choice;
3. Install TeXiFy IDEA plugin;
4. Configure inverse-search in Intellij IDEA for the chosen pdf viewer: Tools -> LaTeX -> Configure Inverse Search. Inverse-search enables the user to jump from the pdf to the corresponding tex file source.

Add a new subproject

1. Create in root folder a new folder with the name of the subproject;

2. Go to settings.gradle.kts and add the new subproject with:

   include(":subproject-name")

3. Compile and build pdf, resolving any bibliographic references, with the Gradle task buildPdf using the Gradle Panel (usually located on the right side of the IDE) or the following command in the terminal in the root directory:

   ./gradlew :subproject-name:buildPdf

4. [Optional] Configure alternative names for the subproject directories and the main tex file in the build.gradle.kts file:

   • Create a build.gradle.kts file in the subproject directory;

   • Add the following code:

     ext.set("variable", "value")

     Variable	Default value	Description
     srcDirName	src	name of the tex source file's directory
     outDirName	out	name of the output directory, where the pdf file will be generated to
     auxDirName	auxil	name of the auxiliary directory, where the auxiliary files will be generated to
     mainTexFileName	main	name of the main tex file
     useBibtex	true	use bibtex to resolve bibliography references

5. [Optional] If no changes are made to the bibliography references in development, it is possible to speed up the compilation process by using IDEA's run configuration in the <main>.tex file instead of the Gradle task buildPdf. This is because the latter has more compiler iterations to resolve the bibliography references.

   • In the run configuration panel, edit the paths to the corresponding subproject directories:

   Edit Run Configuration

   • To compile the document use the shortcut Shift + F10 or the gutter icon Run.

Important

It is advised to not delete the generated auxiliary files as they can be used in subsequent compilations to speed up the process.

Compile and build all subprojects

Manually

To compile and build all pdfs in all subprojects, use the Gradle task buildAllPdfs which can be found in the Gradle Panel or by running the following command in the terminal:

./gradlew buildAllPdfs

Automatically

A workflow using GitHub Actions is set up to automatically compile and build all pdfs in all subprojects when a push is made to the repository in the default branch (usually main or master) or when a pull request is opened to the default branch. Can be further customized to run on other branches, tags and/or other events, even on chron schedules. Learn more here.

Additionally, if you're certain about which folders will store the documents, you can restrict the workflow trigger to those specific folders. This ensures that only changes in those folders will activate the workflow, regardless of the triggering event.

Note

This workflow can also be triggered manually in GitHub be accessing Actions > Compile and build all latex documents > Run Workflow.