Rework on project structure and CI/CD

[noradefitero]

BREAKING CHANGES!

Description

Due to the spontaneous nature of the project's beginnings, its structure and workflows were developed somewhat incrementally and without a consistent standard.

This PR focuses on reorganizing the project, establishing consistent development standards, and improving the CI/CD workflows to automate documentation generation and distribution.

It also includes several documentation fixes, formatting improvements, and corrections to the manual.

Type of Change

• New feature
• Bug fix
• Refactoring (no functional changes)
• Documentation update
• Infrastructure / CI/CD
• Performance improvement

Changes Made

Project structure

• Renamed and reorganized the documentation sources, separating the manual source from generated files.
• Removed generated files from version control where appropriate.
• Updated .gitignore rules for generated files, README.md, and node_modules.
• Cleaned up obsolete CI/CD files and dead workflow code.
• Added the required CHANGELOG.md and version.txt files for release management.

CI/CD & Releases

• Added and reorganized GitHub Actions workflows for:
  • Continuous linting on pushes and pull requests.
  • Automated documentation generation.
  • PDF and Markdown distribution.
  • Release management with Release Please.
  • Publishing compiled documentation on version tags.
    ts.
• Added automated release/version management through Release Please.
• Automated README generation and updates on releases.
• Added GitHub release badges and links to the generated README.

Code & Documentation Quality

• Added and configured project-wide linters and formatters.

• Added pre-commit hooks for:

  • Markdownlint
  • Prettier
  • ChkTeX

• Added formatting and linting rules for Markdown and LaTeX sources.

• Configured generated files to be ignored by the appropriate linters and formatters.

• Updated the Markdown and LaTeX templates to produce lint-compliant output.

• Applied consistent formatting to the manual and its templates.

Manual improvements

• Corrected several typos and documentation errors.
• Fixed the ordering of conditional statements in the Markdown template.
• Fixed the title-page image to use an absolute URL.
• Updated terminology in the collaboration section.
• Added and adapted functions to better fit the Python context.
• Improved the generated documentation and README.

Documentation generation

• Improved the Makefile targets used to generate documentation.
• Removed unnecessary heading manipulation from generated documentation.
• Added the required dependencies for PDF generation, including Pandoc, LaTeX, and additional fonts.
• Configured ChkTeX to skip the third-party PDF template.
• Added automated generation of Markdown and PDF documentation.

How to Test

1. Clone the repository and install the required development dependencies.
2. Install the pre-commit hooks.
3. Run the project's Makefile targets to generate the Markdown and PDF documentation.
4. Verify that the generated documentation is correctly formatted and that no unexpected generated files are tracked.
5. Run the configured linters and verify that they pass.
6. Push a branch or open a pull request and verify that the CI workflows execute successfully.
7. Create a version tag/release and verify that the release workflow publishes the generated documentation correctly.

Checklist

• Code follows the project's style guidelines
• Self-reviewed the code for obvious errors
• Updated documentation if needed
• No new warnings or console errors introduced

[noradefitero]

Super-linter summary

Language	Validation result
CHECKOV	Pass ✅
GITHUB_ACTIONS	Pass ✅
GITHUB_ACTIONS_ZIZMOR	Pass ✅
GITLEAKS	Pass ✅
GIT_MERGE_CONFLICT_MARKERS	Pass ✅
JSCPD	Pass ✅
JSON	Pass ✅
JSON_PRETTIER	Pass ✅
LATEX	Pass ✅
MARKDOWN	Pass ✅
MARKDOWN_PRETTIER	Pass ✅
NATURAL_LANGUAGE	Fail ❌
PRE_COMMIT	Pass ✅
SPELL_CODESPELL	Fail ❌
TRIVY	Pass ✅
YAML	Pass ✅
YAML_PRETTIER	Pass ✅

Super-linter detected linting errors

For more information, see the GitHub Actions workflow run

Powered by Super-linter
Super-linter revision: 2da136927bd4a73596db63044b504547c62cb854
Super-linter version: 9.0.0

NATURAL_LANGUAGE

/github/workspace/README.md
  162:12  ✓ error  Incorrect term: “zsh”, use “Zsh” instead      terminology
  467:60  ✓ error  Incorrect term: “png”, use “PNG” instead      terminology
  468:22  ✓ error  Incorrect term: “png”, use “PNG” instead      terminology
  470:50  ✓ error  Incorrect term: “png”, use “PNG” instead      terminology
  522:63  ✓ error  Incorrect term: “MacOS”, use “macOS” instead  terminology
  562:62  ✓ error  Incorrect term: “MacOS”, use “macOS” instead  terminology

✖ 6 problems (6 errors, 0 warnings, 0 infos)
✓ 6 fixable problems.
Try to run: $ textlint --fix [file]

SPELL_CODESPELL

/github/workspace/README.md:381: Theses ==> These, Thesis

[noradefitero]

Until I release a version, I shouldn't delete the README.md and README.pdf files in the root of the repo, so I'm reverting the changes to those two files

[noradefitero]

Super-linter summary

Language Validation result
CHECKOV Pass ✅
GITHUB_ACTIONS Pass ✅
GITHUB_ACTIONS_ZIZMOR Pass ✅
GITLEAKS Pass ✅
GIT_MERGE_CONFLICT_MARKERS Pass ✅
JSCPD Pass ✅
JSON Pass ✅
JSON_PRETTIER Pass ✅
LATEX Pass ✅
MARKDOWN Pass ✅
MARKDOWN_PRETTIER Pass ✅
NATURAL_LANGUAGE Fail ❌
PRE_COMMIT Pass ✅
SPELL_CODESPELL Fail ❌
TRIVY Pass ✅
YAML Pass ✅
YAML_PRETTIER Pass ✅
Super-linter detected linting errors

For more information, see the GitHub Actions workflow run

Powered by Super-linter Super-linter revision: 2da136927bd4a73596db63044b504547c62cb854 Super-linter version: 9.0.0

NATURAL_LANGUAGE

/github/workspace/README.md
  162:12  ✓ error  Incorrect term: “zsh”, use “Zsh” instead      terminology
  467:60  ✓ error  Incorrect term: “png”, use “PNG” instead      terminology
  468:22  ✓ error  Incorrect term: “png”, use “PNG” instead      terminology
  470:50  ✓ error  Incorrect term: “png”, use “PNG” instead      terminology
  522:63  ✓ error  Incorrect term: “MacOS”, use “macOS” instead  terminology
  562:62  ✓ error  Incorrect term: “MacOS”, use “macOS” instead  terminology

✖ 6 problems (6 errors, 0 warnings, 0 infos)
✓ 6 fixable problems.
Try to run: $ textlint --fix [file]

SPELL_CODESPELL

These errors are in files from before the PR that are auto-generated, so I'll set Super Linter to ignore them.