Skip to main content

Automated Documentation Systems

This document describes how documentation is generated, managed, and updated in the Tower Defense project.

1. Documentation as Code (DaC)​

The project follows a Documentation as Code approach, where all documentation is stored alongside the source code in the same repository.

Docusaurus (Current Site)​

  • Engine: Docusaurus v3
  • Content: Written in Markdown (MD) and MDX for interactive components.
  • Location: apps/docs
  • Deployment: Automatically built and deployed via CI/CD pipelines.

2. API Documentation (OpenAPI)​

The backend API is designed to support automated documentation generation from the source code.

  • Standard: OpenAPI (Swagger)
  • Integration: (Planned) We plan to use docusaurus-plugin-openapi-docs to automatically import and display the API reference within this site.
  • Update Frequency: Re-generated on every build of the api project.

3. Diagram Generation (Mermaid)​

Architecture diagrams and flowcharts are rendered directly from text using Mermaid.js.

  • Example:

4. Nx Documentation Tools​

We use the following Nx commands to manage and update the project documentation:

  • pnpm nx run docs:serve: Start a local development server for the documentation site.
  • pnpm nx run docs:build: Generate production-ready static files for the documentation site.

5. Future Automation Plans​

  • Typedoc for Game: Automatically generate API references for the Angular game client.
  • Doxygen / Sphinx: (If needed) For low-level library documentation.
  • Automated Screenshots: Generate and update screenshots in the documentation via E2E testing tools.
info

By following these practices, we ensure that our documentation is always up-to-date and easily accessible to all developers.