Skip to content

Last Updated: 2026-05-04 Owner: Docs-Dev Summary: Step-by-step guide for moving the QuantMatrix documentation into the GitHub repository and checking in only the docs-related files.

QuantMatrix GitHub Docs Check-In Steps

This guide explains how to move the documentation work from this local Codex workspace into the real GitHub repository:

Use this guide when: - the current working folder is not a Git repository - you want to check in only the documentation assets - you want the cleanest and lowest-risk path into GitHub

The safest approach is:

  1. clone the real GitHub repository locally
  2. copy the documentation files into that repository
  3. add only the docs-related paths
  4. commit and push

This is safer than turning the current generated Codex folder directly into the repo.

2. What Should Be Checked In

Include:

  • documentation/docs/
  • documentation/portal/
  • documentation/tools/
  • documentation/mkdocs.yml
  • documentation/requirements-docs.txt
  • .github/workflows/docs-site.yml
  • .github/pull_request_template.md
  • README.md
  • .gitignore

Do not include:

  • documentation/site/
  • .venv-docs/
  • .env

3. Clone The Real Repository

Go to the location where you keep your real projects, then clone the repo:

cd /Users/dhinakarmanni/projects
git clone https://github.com/mdhinakar/quantmatrix.git
cd quantmatrix

4. Copy The Documentation Into The Repo

Copy the documentation assets from this Codex workspace into the cloned repository:

cp -R /Users/dhinakarmanni/Documents/Codex/2026-05-02/read-project-spec-md-and-generate/documentation .
mkdir -p documentation
cp /Users/dhinakarmanni/Documents/Codex/2026-05-02/read-project-spec-md-and-generate/documentation/mkdocs.yml documentation/
cp /Users/dhinakarmanni/Documents/Codex/2026-05-02/read-project-spec-md-and-generate/documentation/requirements-docs.txt documentation/
cp /Users/dhinakarmanni/Documents/Codex/2026-05-02/read-project-spec-md-and-generate/README.md .
mkdir -p .github/workflows
cp /Users/dhinakarmanni/Documents/Codex/2026-05-02/read-project-spec-md-and-generate/.github/workflows/docs-site.yml .github/workflows/
cp /Users/dhinakarmanni/Documents/Codex/2026-05-02/read-project-spec-md-and-generate/.github/pull_request_template.md .github/

5. Add A .gitignore

If the repo does not already have the right ignore rules, use:

__pycache__/
*.py[cod]
.pytest_cache/
.mypy_cache/
.ruff_cache/

.venv/
.venv-docs/
venv/
env/

.env
.env.*
!.env.example

build/
dist/
*.egg-info/

documentation/site/
site/

.DS_Store
.idea/
.vscode/

.coverage
coverage.xml
htmlcov/

*.log

Run:

git add documentation/docs
git add documentation/portal
git add documentation/tools
git add documentation/mkdocs.yml
git add documentation/requirements-docs.txt
git add .github/workflows/docs-site.yml
git add .github/pull_request_template.md
git add README.md
git add .gitignore

7. Review Before Committing

Before committing, confirm the staged set only contains docs-related changes.

The staged files should mainly be:

  • documentation/docs/...
  • documentation/portal/...
  • documentation/tools/...
  • documentation/mkdocs.yml
  • documentation/requirements-docs.txt
  • .github/workflows/docs-site.yml
  • .github/pull_request_template.md
  • README.md
  • .gitignore

8. Commit

Recommended commit message:

git commit -m "Reorganize docs under documentation/ and add MkDocs publishing setup"

9. Push

If you are committing directly to main:

git push origin main

If you are using a feature branch:

git push origin <branch-name>

10. Enable GitHub Pages

After the push:

  1. open the repo on GitHub
  2. go to Settings
  3. open Pages
  4. set Source to GitHub Actions

11. Verify The Docs Workflow

Then:

  1. open the Actions tab
  2. open the docs-site workflow
  3. confirm:
  4. build succeeds
  5. deploy succeeds

12. Hosted Docs Target

The intended hosted docs URL is:

Use this order:

  1. clone repo
  2. copy docs into repo
  3. add .gitignore
  4. stage only docs-related files
  5. commit
  6. push
  7. enable GitHub Pages
  8. verify docs-site workflow
  9. open hosted docs

14. Best Next Step

Once the docs are in GitHub, the next best step is:

  • run the GitHub Pages publishing checklist and verify the first hosted docs release end to end