first documentation pipeline

Author: yamilbknsu

.github/workflows/docs.yml

@@ -0,0 +1,40 @@
+name: 📖 Build & Deploy Docs
+
+on:
+  push:
+    branches:
+      - main
+      - dev
+      - 'yep/**'
+    tags:
+      - 'v*.*.*'
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: "${{ (github.ref == 'refs/heads/main' || github.ref == 'refs/heads/dev') ? 0 : 1 }}"
+      
+      - name: Set up Python Environment
+        uses: actions/setup-python@v4
+        with:
+          python-version: '3.10'
+      
+      - name: Install dependencies
+        run: |
+          python -m pip install --upgrade pip
+          pip install ".[docs]"
+      
+      - name: Build HTML docs
+        working-directory: docs
+        run: make html
+        
+      - name: Deploy to GitHub Pages
+        uses: peaceiris/actions-gh-pages@v4
+        with:
+          github_token: ${{ secrets.GITHUB_TOKEN }}
+          publish_dir: docs/build/html
+          publish_branch: gh-pages
+

.gitignore

@@ -3,4 +3,6 @@
 demos/outputs/simulation/**/*
 demos/outputs/figures
 .DS_Store
-.vscode
+.vscode
+build/
+*.egg-info

README.md

@@ -2,8 +2,8 @@
 
 >**TODO:** The previous description from Urbansim it outdated. Add description of DEMOS, aligning with the code (paper).
 
-# Usage
-## Docker Container
+## Usage
+### Docker Container
 The docker image for demos is stored in `registry/demos:latest`. The input data and configuration file are fed to the container through volumes. Alternatively, we provide a `docker-compose` workflow that can be used.
 
 For running the `docker-compose` workflow:
@@ -18,15 +18,15 @@ Alternatively,
 docker run --volume <path-to-config>:/demos/config.toml:ro --volume <path-to-data-dir>:/demos/data --platform=linux/amd64 demos
 ```
 
-### IMPORTANT for MacOS and Windows users
+#### IMPORTANT for MacOS and Windows users
 Docker imposes a global limit on how much RAM containers can allocate. DEMOS easily surpases those limits, so in order to run DEMOS in Docker, users need to access the Docker Desktop GUI and `Preferences → Resources → Memory → Increase it (at least 16-20gb)`
 
-### Building the docker image (development only)
+#### Building the docker image (development only)
 ```bash
 docker build -t demos:0.0.1 --platform=linux/amd64 -f Dockerfile .
 ```
 
-## From Source
+### From Source
 
 This repository contains only code and configuration/setup files necessary 
 
@@ -90,7 +90,7 @@ the demos simulation will produce the following sets of data and results:
   - a synthetic population file showing the evolution of the synthetic population throughout the simulation years. the file should be named `model_data_<scenario_name_output_year>.h5` in directory `DEMOS_NREL/demos/data`.
   - series of aggregated statistics for the population size, number of households, household size distribution, gender distribution, number of births, number of mortalities, number of student enrollments, number of total marriages, number of total divorces, the age distribution of the synthetic population, and income distribution for each simulation year. The files are located at `DEMOS_NREL/demos/outputs/simulation`
 
-## ii. project structure
+### ii. project structure
 >**TODO:** this part still need to be complemented
 
 the main folder of this repository contains several python scripts that contain the different steps necessary to import, process, and run the demos framework. the following is a description of the different folder and scripts used to run the demos simulation

data/.gitignore

@@ -1,4 +1,3 @@
-
 *
 !.gitignore
 !outputs/

demos/__init__.py

@@ -0,0 +1,5 @@
+"""
+DEMOS - Demographic Micro-Simulator
+
+A microsimulation framework for demographic and economic modeling.
+"""