Initial commit

.devcontainer/devcontainer.json

@@ -0,0 +1,18 @@
+// For format details, see https://aka.ms/devcontainer.json. For config options, see the
+// README at: https://github.com/devcontainers/templates/tree/main/src/debian
+{
+	"name": "dissertation-latex",
+	// Or use a Dockerfile or Docker Compose file. More info: https://containers.dev/guide/dockerfile
+	"image": "mcr.microsoft.com/devcontainers/base:bullseye",
+	"features": {
+		"ghcr.io/prulloac/devcontainer-features/latex:1": {
+			"scheme": "small",
+			"packages": "texdoc,collection-latexrecommended,collection-fontsrecommended,courier-scaled,nextpage,enumitem,epigraph,cleveref"
+		}
+	}
+
+	// , // Add if some latex programs are not found, probably the ones installed with the terminal with tlmgr
+	// "remoteEnv": {
+	// 	"PATH": "${containerEnv:PATH}:/usr/local/texlive/2023/bin/x86_64-linux"
+	// }
+}

.github/workflows/build-and-publish-document.yml

@@ -0,0 +1,60 @@
+name: build-and-publish-document
+on:
+  push:
+    paths:
+      - 'document/**'
+  workflow_dispatch:
+
+permissions:
+  contents: write
+
+jobs:
+  build-and-publish-document:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout repo
+        uses: actions/checkout@v4
+      - name: Compile LaTeX document
+        uses: xu-cheng/latex-action@v3
+        with:
+          work_in_root_file_dir: true
+          # Add more tex files if needed
+          root_file: |
+            document/main.tex
+      - run: |
+          cp ./document/main.pdf document.pdf
+        # Add more pdf files if needed
+      - name: Publish document
+        uses: actions/upload-artifact@v4
+        with:
+          name: Document
+          path: document.pdf
+
+  create-release:
+    if: github.ref == 'refs/heads/main'
+    runs-on: ubuntu-latest
+    needs: build-and-publish-document
+    steps:
+      - uses: actions/checkout@v4
+      - name: Get the artifact
+        uses: actions/download-artifact@v4
+        with:
+          name: Document
+      - name: Delete previous release
+        uses: ClementTsang/delete-tag-and-release@v0.3.1
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        with:
+          tag_name: latest
+          delete_release: true
+      - run: sleep 4
+      - name: Create a release
+        uses: softprops/action-gh-release@v1
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        with:
+          name: Latest document version
+          tag_name: latest
+          generate_release_notes: true
+          files: |
+            document.pdf

LICENSE.txt

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) [year] [fullname]
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

README.md

@@ -0,0 +1,48 @@
+# Dissertation repository template
+> A template repository for dissertations.
+
+If your dissertation is already reaching the compilation limits of [Overleaf](https://www.overleaf.com/), you are overly paranoid about you data safety/security, you want to use `git` for version management or you simply want to have a local copy of your dissertation, ready to use with your favourite editor and tools, this template is for you.
+
+## Desiderata
+- [x] DevContainers [Open-Source specification](https://containers.dev/) / [VSCode docs](https://code.visualstudio.com/docs/devcontainers/containers) environment for [LaTeX](https://en.wikipedia.org/wiki/LaTeX) development with [VSCode](https://code.visualstudio.com/) and the [LaTeX Workshop extension](https://marketplace.visualstudio.com/items?itemName=James-Yu.latex-workshop).
+- [x] [GitHub Actions](https://github.com/features/actions) to build the document and publish it as an artifacts or release.
+
+## Directory structure
+```bash
+dissertation-template/
+├─ .devcontainer/                          # DevContainer configuration
+│  ├─ devcontainer.json                    # DevContainer configuration file
+├─ .github/                                # GitHub Actions configuration
+│  ├─ workflows/                           # GitHub Actions workflows
+│  │  ├─ build-and-publish-document.yml    
+├─ document/                               # Document and bibliography
+├─ logbook/                                # Logs of meetings and progresss
+├─ research/                               # Research papers
+```
+
+Further explanation of the directory structure can be found inside the `README.md` files in each directory.s
+
+## Requirements to use DevContainers
+- [Docker](https://www.docker.com/)
+- [VSCode](https://code.visualstudio.com/)
+- [VSCode Remote development extension pack](https://marketplace.visualstudio.com/items?itemName=ms-vscode-remote.vscode-remote-extensionpack)
+
+The first time you open the project in VSCode, you will be prompted to reopen the project in a container. If you miss this prompt, you can always reopen the project in a container by clicking the green icon in the bottom left corner of the VSCode window.
+
+This configuration uses [prulloac](https://github.com/prulloac)'s [DevContainer feature](https://github.com/prulloac/devcontainer-features/tree/main/src/latex) in a [Debian](https://www.debian.org/) container. The feature installs [TeXLive](https://www.tug.org/texlive/) small scheme and the LaTeX Workshop extension. Some other packages are added to the container to make the development experience more pleasant:
+- `texdoc`
+- `collection-latexrecommended`
+- `collection-fontsrecommended`
+- `courier-scaled`
+- `nextpage`
+- `enumitem`
+- `epigraph`
+- `cleveref`
+
+Other latex packages can be installed by adding them to the `packages` array in the `devcontainer.json` file or by running `tlmgr install <package>` in the container.
+
+## State of the GitHub Actions workflow
+### Build and publish document
+- Triggers if a push is made modifying the `document/` directory
+- Builds the document and stores it as an artifact (inside a zip file 😔)
+- If the push is in the main branch it replaces the tag `latest` and its release with the updated document and commit. The document pdf is one of the assets of the release.

document/.gitignore

@@ -0,0 +1,8 @@
+*.aux
+*.fls
+*.fdb_latexmk
+*.log
+*.out
+*.synctex.gz
+*.toc
+/*.pdf

document/README.md

@@ -0,0 +1,10 @@
+# Document directory
+Your dissertation will live here. To get started simply replace the `main.tex` file or, if you started already (maybe in [Overleaf](https://www.overleaf.com/)), just copy the contents of your project and make sure the main document's name is `main.tex` (optionally, change the name in the [action workflow](../.github/workflows/build-and-publish-document.yml) to use a different name in the `Compile LaTeX document` step). From Overleaf you can download the project as a zip file and extract it here. You might need to add some LaTeX packages in the DevContainer's environment; you can do so by adding the packages to DevContainer's configuration file ([`devcontainer.json`](../.devcontainer/devcontainer.json)) under `features.ghcr.io/prulloac/devcontainer-features/latex:1.package`(persist through container recreations) or by using the command line inside the DevContainer with `tlmgr install <package_name>` (need to be added every time the container is rebuilt). 
+
+If you are compiling more than one file make sure to add them to the action in the `Compile LaTeX document` step, to save the outputs as artifacts and to add them to the release to have the compiled pdfs available in the GitHub repository. 
+
+## If you came here from [FEUP](https://sigarra.up.pt/feup/en/web_page.Inicial)
+If you are a student at FEUP, you can unzip the template provided by the Dissertation Planning course unit or get the [template available in Overleaf](https://www.overleaf.com/latex/templates/feup-dissertation-format/qrsrxjjwzrzf) by opening it and downloading it as a zip file. See some documentation from the [creator](https://sigarra.up.pt/feup/pt/func_geral.formview?p_codigo=230756) himself [here](https://web.fe.up.pt/~jlopes/doku.php/teach/feupteses).
+
+## Bibliography management recommendations
+Throughout your dissertation it is important to manage the bibliography. There are many fully featured bibliography managers available, capable of exporting to LaTeX supported formats, (including open-source ones, like [Zotero](https://www.zotero.org/)), but I was seeking for something simpler that would use a simple file, something like a frontend for BibTex or biblatex. I ended up using [JabRef](https://www.jabref.org/), that uses the either of the formats and implements its features using comments to store all the necessary metadata. It has a browser extension for adding entries to the database and a lot of other features. JabRef can enrich your entries with data metadata from the web, query online aggregators and even search for the pdf files or metadata of your entries. You also can link your bibliography entries to the pdf files in the [`../research`](../research) directory and it will open them in your default pdf viewer. I recommend it. The best thing is that you can include the file directly in your LaTeX documents and start citing away.  

document/main.tex

@@ -0,0 +1,11 @@
+\documentclass[]{article}%%%%%%%%%%%%%%%%%%%% Packages/Macros %%%%%%%%%%%%%%%%%%%%\usepackage{amssymb,latexsym,amsmath}     % Standard packages%%%%%%%%%%%% Margins %%%%%%%%%%%%\addtolength{\textwidth}{1.0in}\addtolength{\textheight}{1.00in}\addtolength{\evensidemargin}{-0.75in}\addtolength{\oddsidemargin}{-0.75in}\addtolength{\topmargin}{-.50in}%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% Theorem/Proof Environments %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%\newtheorem{theorem}{Theorem}\newenvironment{proof}{\noindent{\bf Proof:}}{$\hfill \Box$ \vspace{10pt}}  %%%%%%%%%%%%% Document %%%%%%%%%%%%%\begin{document}
+
+\title{Sample \LaTeX ~File}
+\author{David P. Little}
+\maketitle
+
+\begin{abstract}
+This document represents the output from the file ``sample.tex" once compiled using your favorite \LaTeX compiler.  This file should serve as a good example of the basic structure of a ``.tex" file as well as many of the most basic commands needed for typesetting documents involving mathematical symbols and expressions.  For more of a description on how each command works, please consult the links found on our course webpage.
+\end{abstract}
+
+\section{Lists}%%%%%%%%%%%%%%%\begin{enumerate}\item {\bf First Point (Bold Face)}\item {\em Second Point (Italic)}\item {\Large Third Point (Large Font)}    \begin{enumerate}        \item {\small First Subpoint (Small Font)}         \item {\tiny Second Subpoint (Tiny Font)}         \item {\Huge Third Subpoint (Huge Font)}     \end{enumerate}\item[$\bullet$] {\sf Bullet Point (Sans Serif)}\item[$\circ$] {\sc Circle Point (Small Caps)} \end{enumerate}\section{Equations}%%%%%%%%%%%%%%%%%%%\subsection{Binomial Theorem}\begin{theorem}[Binomial Theorem]For any nonnegative integer $n$, we have$$(1+x)^n = \sum_{i=0}^n {n \choose i} x^i$$\end{theorem}\subsection{Taylor Series}The Taylor series expansion for the function $e^x$ is given by\begin{equation}e^x = 1 + x + \frac{x^2}{2} + \frac{x^3}{6} + \cdots = \sum_{n\geq 0} \frac{x^n}{n!}\end{equation}\subsection{Sets}\begin{theorem}For any sets $A$, $B$ and $C$, we have$$ (A\cup B)-(C-A) = A \cup (B-C)$$\end{theorem}\begin{proof}\begin{eqnarray*}(A\cup B)-(C-A) &=& (A\cup B) \cap (C-A)^c\\&=& (A\cup B) \cap (C \cap A^c)^c \\&=& (A\cup B) \cap (C^c \cup A) \\&=& A \cup (B\cap C^c) \\&=& A \cup (B-C)\end{eqnarray*}\end{proof}\section{Tables}%%%%%%%%%%%%%%%%\begin{center}\begin{tabular}{l||c|r}left justified & center & right justified \\ \hline1 & 3.14159 & 5 \\2.4678 & 3 &  1234 \\ \hline \hline3.4678 & 6.14159 & 1239\end{tabular}\end{center}\section{A Picture}%%%%%%%%%%%%%%%%%%%\begin{center}\begin{picture}(100,100)(0,0)\setlength{\unitlength}{1pt}\put(20,70){\circle{30}}  \put(20,70){\circle*{10}}   % left eye\put(80,70){\circle{30}}  \put(80,70){\circle*{10}}   % right eye\put(40,40){\line(1,2){10}} \put(60,40){\line(-1,2){10}} \put(40,40){\line(1,0){20}} % nose\put(50,20){\oval(80,10)[b]} % mouth\multiput(0,90)(4,0){10}{\line(1,3){4}}  % left eyebrow\multiput(100,90)(-4,0){10}{\line(-1,3){4}}  % right eyebrow\end{picture}\end{center}\end{document}

logbook/README.md

@@ -0,0 +1,4 @@
+# Logbook directory
+During the course of your dissertation, you will have to meet with your supervisor(s) and other people. This directory is intended to save your meeting notes so you don't forget any of their feedback, suggestions, requests or decisions. You can also log here the progress of your tasks and writing.
+
+Use something like [markdown](https://www.markdownguide.org/) to make taking notes fast and easy. 

research/README.md

@@ -0,0 +1,2 @@
+# Research directory
+This directory is intended to save research papers and notes. Files can be linked to your bibliography manager of choice for easier access.