📄 Mkdocs: Configuring mkdocs.yml

Once we have our project structure set up, we will configure it step by step, starting with the mkdocs.yml file. This file defines the structure and settings for your documentation site. Here's how it should be structured:

mkdocs.yml

site_name: Hospital Documentation  

nav:

  - Home: index.md

  - Synthea Tables: tables.md

  - AWS Architectur: architecture.md

  - Glossary: glossary.md

markdown_extensions:

  - pymdownx.superfences:

      custom_fences:

        - name: mermaid

          class: mermaid

theme:

  name: material                

In this configuration file, you can primarily see in the nav section the pages that will be accessible from the menu. Then, we specify the Mermaid extension, which will be explained in the next section. Finally, the theme section applies the Material theme, enabling styling and components available within this library.

✏️ Mkdocs: Mermaid Extension

As mentioned earlier, Mermaid is a JavaScript library for creating diagrams and charts from text. Below, we will see some examples. In our case, we will use it to generate an Entity Relationship Diagram (ERD) on the tables page of the documentation.

.

⚙️ Mkdocs: Dynamic Content with Jinja

To enable dynamic content generation for our documentation site, we’ll use Jinja to process templates and replace placeholders with actual data. Below is a step-by-step breakdown:

1. Set Up a templates Folder
   
   
   Create a folder named templates to store all Markdown files for the site. These files should include placeholders. For instance, in index.md, you might have placeholders like {{database.version_date}} and {{database.version}}.




2. Utilize Placeholders
   
   
   Placeholders are dynamic variables in the Markdown files. These variables will be updated automatically using Python dictionaries to inject relevant data.



3. 
   

   Generate Dynamic Content with update.py

   
   
   
   
   
   • Prepare your Markdown templates by identifying the sections where dynamic data is required.
     
   
   
   • Use a Python script (update.py), available in my repository, to process the templates. The script performs the following tasks:
     
     
     
     
     • 
       Database Connection: Connects to a SQLite database to fetch the latest values.
       
     
     
     • 
       Template Rendering: Uses the Jinja library to substitute placeholders with data from the database.
       
     
     
     • 
       File Generation: Outputs updated Markdown files to the docs folder, ready for rendering in MkDocs.
     
     
     
     
   
   
   
   

🦖 Docusaurus Implementation

In the following sections, I will provide detailed steps and insights on how to implement a documentation site using Docusaurus. This includes setup, customization, and deployment options.

🚀 Key Features of Docusaurus

• 📶 Mermaid Support: Similar to MkDocs, Docusaurus supports Mermaid for embedding diagrams.
  


• ⚛️ React Components: Built on React, Docusaurus enables the integration of dynamic components into your documentation.
  


• 🔄 Dynamic Content: Leverages Python scripts to fetch and update content dynamically from an SQLite database.
  

🔧 Docusaurus Setup: From Scratch

To get started with Docusaurus, we follow a quick setup process, which is very similar to the steps we used for MkDocs but with different tools.

1. 
   Create a New Docusaurus Project:
   First, install Node.js and run the following command to create a new Docusaurus site:
   

   npx create-docusaurus@latest my-website classic

1. 
   Install Mermaid Package:
   To enable Mermaid diagrams, install the required package:
   

   npm install @docusaurus/theme-mermaid

1. 
   Run the Development Server:
   Once installed, navigate to your project directory and run the development server:
   

   cd my-website

   npx docusaurus start

1. 
   Visit the Site:
   Your site will be live locally at: http://localhost:3000.

🔧 Docusaurus Customization: Configuration

The configuration file docusaurus.config.js is where we customize the title, theme, navigation, and enable features like Mermaid for diagram rendering.

Example snippet for enabling Mermaid:

module.exports = {

  title: 'Hospital Documentation',

  tagline: 'Documentation for Hospital Data ML Project',

  favicon: 'img/favicon.ico',

  url: 'https://your-site-url.com',

  markdown: {

    mermaid: true,  // Enable Mermaid diagrams

  },

  themeConfig: {

    navbar: {

      title: 'Hospital Docs',

      items: [

        { to: 'docs/', label: 'Home', position: 'left' },

        { to: 'docs/tables', label: 'Tables', position: 'left' },

        { to: 'docs/architecture', label: 'Architecture', position: 'left' },

        { to: 'docs/glossary', label: 'Glossary', position: 'left' },

      ],

    },

    footer: {

      style: 'dark',

      links: [

        { label: 'GitHub', href: 'https://github.com/your-repo' },

      ],

    },

  },

};

🔧 Docusaurus Customizing the Homepage

To customize the homepage, we modify the src/components/HomepageFeatures/index.js file. Here, you can adjust the FeatureList object to update the features displayed on the homepage.

⚙️ Dynamic Data with Jinja

To incorporate dynamic content, such as database tables, we use a 🐍Python script named update.py, which you can find in the repository.

This script fetches data from a SQLite database and processes the Markdown files stored in the templates folder. It then updates these files with the fetched data and copies them into the docs folder, preparing them for site rendering.

This workflow ensures that the content remains up-to-date and ready for deployment, following a similar approach to what we implemented with MkDocs.

⚙️ Docusaurus: Final Workflow

1. 
   Create Templates: Develop your Markdown files within the docs/template directory.


2. 
   Run Python Script: Use the script to dynamically populate data into the templates.


3. 
   Preview Locally: Run npx docusaurus start to preview the site.


4. 
   Build for Deployment: Once ready, use npx docusaurus build to generate the static site.


5. 
   Deploy: Host the static files on your preferred platform, such as AWS S3.

🚀 Deployment

In this section, we will cover the deployment process for both MkDocs and Docusaurus using AWS S3 for hosting. While the deployment steps are the same for both tools, the installation processes differ, with MkDocs being Python-based and Docusaurus being JavaScript-based.

Infrastructure Setup with Terraform

To deploy a static documentation site to AWS S3, we use Terraform to provision and configure the required resources. The setup defines the S3 bucket, enables static website hosting, and configures public access with a bucket policy to allow read-only access. You can find the main.tf file in the repository.

🚀 Key Components for S3 Deployment

1. 
   S3 Bucket Creation: The resource to create the S3 bucket where the documentation will be hosted.


2. 
   Static Website Hosting: Configuration for static web hosting, setting the index.html and error.html as the main and error documents.


3. 
   Public Access Configuration: Manages public access to the S3 bucket, ensuring it is configured for read-only access.


4. 
   Bucket Policy: Allows public access to retrieve the documentation content from the S3 bucket.

You can access the complete Terraform file and the corresponding configurations for deploying the site in the repository:

Terraform Configuration File:

GitHub Action Workflow for Automatic Deployment: A CI/CD pipeline to automate the deployment process is also included in the repository.

GitHub Actions Configuration

Make sure to configure your AWS credentials in the GitHub repository secrets under Settings > Secrets > Actions. This will allow GitHub Actions to securely access your AWS account and perform actions like uploading files to S3 when you push changes to the main branch.

Repositories

Below are the links to all the code to deploy your documentation site. If you find it useful, you can leave a star ⭐️ and follow me to receive notifications of new articles. This will help me grow in the tech community and create more content.

• 
  MkDocs Deployment: /
  
  
  
  
  

  ⚙️ Doc as Code Tutorial

  
  
  
  
  
  
  

  🚀 MkDocs & MkDocs-material

  
  
  
  
  

  MkDocs is an excellent solution for implementing a documentation portal that can be easily updated with code, helping to keep your software development project documentation up-to-date and versioned.

  
  
  

  In this repository, I have created a simple site to document the data model and machine learning project.

  
  
  

  The documentation will include charts, tables, and architecture examples, providing a comprehensive and easy-to-understand guide on how to implement this framework in combination with two other 🐍Python libraries.

  
  
  
  
  

  What is Documentation as Code?

  
  
  
  
  

  Documentation and its updates are an important process in many companies that develop software, where this process is carried out using different tools, many of which are paid solutions.
  
  Therefore, in recent times, the concept of "doc as code" has emerged. This means using the same tools and workflow used in software development to manage, version, and…