Skip to content

Commit edf0b1c

Browse files
twardochtwardoch
authored
Merge pull request #2 from fontlabcom/terragon/create-review-folder-catalog
Add CLA review documentation: file catalog and improvement plan
2 parents e0c1083 + 10b3823 commit edf0b1c

2 files changed

Lines changed: 307 additions & 0 deletions

File tree

‎REVIEW/FILES-cla.md‎

Lines changed: 134 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,134 @@
1+
---
2+
title: Repository File Catalog (CLA Review)
3+
this_file: REVIEW/FILES-cla.md
4+
---
5+
6+
# FontLab Python Docs — File and Folder Catalog
7+
8+
Scope: Catalog of all notable files/folders with a repository tree dump and concise descriptions to support CLA review and onboarding.
9+
10+
## Repository Overview
11+
12+
- Purpose: This repo hosts the source and generated documentation for FontLab 7 Python APIs (FontLab, FontGate) and PythonQt, built with pydocmk2 and MkDocs Material.
13+
- Output site: `docs/` (root HTML docs), optionally `docs/pythonqt/` for PythonQt when built.
14+
15+
## Filesystem Tree (overview)
16+
17+
Note: The `docs/` folder contains hundreds of generated HTML files. For readability, this tree shows all top-level items and key subdirectories. Detailed descriptions below include pattern-based notes for generated files.
18+
19+
```
20+
.
21+
├── .gitignore
22+
├── LICENSE
23+
├── README.md
24+
├── docs/
25+
│ ├── 404.html
26+
│ ├── assets/
27+
│ │ ├── fonts/
28+
│ │ │ ├── font-awesome.css
29+
│ │ │ └── specimen/ (font files: TTF/WOFF/WOFF2)
30+
│ │ ├── images/ (favicon, provider icons)
31+
│ │ ├── javascripts/ (mkdocs assets, lunr search)
32+
│ │ └── stylesheets/ (compiled CSS)
33+
│ ├── FL*.html (FL API pages)
34+
│ ├── fontlab*.html (FontLab API pages)
35+
│ ├── fontgate*.html (FontGate API pages)
36+
│ └── index.html (site index when present)
37+
├── fontlab7/
38+
│ ├── build/
39+
│ │ ├── build_fontlab7_api_docs.command
40+
│ │ ├── build_fontlab7_api_docs.vfpy
41+
│ │ └── build_fontlab7_api_docs.vfpyc
42+
│ ├── mkdocs.yml
43+
│ ├── pydocmk.yml
44+
│ ├── srcdocs/
45+
│ │ ├── docs/ (hand-written pages)
46+
│ │ ├── mkdocs/ (pydocmk2-generated Markdown)
47+
│ │ └── post/ (content appended to generated pages)
48+
│ └── theme/
49+
│ ├── 404.html
50+
│ └── style/
51+
│ └── fontlab_pyapi.css
52+
└── pythonqt/
53+
├── build/
54+
│ ├── build_pythonqt_api_docs.command
55+
│ └── build_pythonqt_api_docs.vfpy
56+
├── mkdocs.yml
57+
├── pydocmk.yml
58+
├── srcdocs/
59+
│ ├── docs/ (hand-written pages)
60+
│ └── mkdocs/ (pydocmk2-generated Markdown)
61+
└── theme/
62+
└── style/
63+
└── fontlab_pyapi.css (inherited/duplicated theme path)
64+
```
65+
66+
## Per-Item Descriptions
67+
68+
- `.gitignore`: Git rules excluding build artefacts and editor cruft.
69+
- `LICENSE`: Apache 2.0 license for the documentation content.
70+
- `README.md`: Project overview, build instructions for FontLab 7 Python API and PythonQt docs, contribution notes with CLA link.
71+
72+
### docs/ (generated site)
73+
74+
- `docs/`: Built HTML documentation site (MkDocs Material). Contents are generated and can be hosted via GitHub Pages.
75+
- `404.html`: Custom 404 page generated by the theme.
76+
- `assets/`: Static assets used by the site.
77+
- `fonts/` + `specimen/`: Webfont binaries used by the theme and icons.
78+
- `images/`: Site images including favicon and provider/social icons.
79+
- `javascripts/`: Theme JS bundles and `lunr/` search language support files.
80+
- `stylesheets/`: Theme CSS bundles.
81+
- `FL*.html`: API reference pages for the high-level `FL` namespace (e.g., `FL.Glyph.html`, `FL.Font.html`). Auto-generated.
82+
- `fontlab*.html`: API reference pages for the `fontlab` namespace (e.g., `fontlab.flGlyph.html`). Auto-generated.
83+
- `fontgate*.html`: API reference pages for the `fontgate` namespace (e.g., `fontgate.fgGlyph.html`). Auto-generated.
84+
- `index.html` (if present): Documentation home.
85+
86+
Note: The repository snapshot shows numerous `FL.*.html`, `fontlab.*.html`, and `fontgate.*.html` files representing classes, modules, and data structures from the FontLab API. These are typical pydocmk2 outputs rendered by MkDocs.
87+
88+
### fontlab7/ (FontLab 7 Python API docs source)
89+
90+
- `fontlab7/mkdocs.yml`: MkDocs site configuration for FontLab 7 API docs. Defines navigation for FL, fontlab, and fontgate sections, theme, extensions, and site output to `../docs`.
91+
- `fontlab7/pydocmk.yml`: pydocmk2 configuration, orchestrating how Python API symbols are transformed into Markdown under `srcdocs/mkdocs` and then into HTML.
92+
- `fontlab7/build/`:
93+
- `build_fontlab7_api_docs.command`: macOS helper script to open the `.vfpy` project in FontLab and trigger doc generation and MkDocs build.
94+
- `build_fontlab7_api_docs.vfpy`: FontLab project file to drive pydocmk2 Markdown generation.
95+
- `build_fontlab7_api_docs.vfpyc`: Compiled/cache variant used by FontLab (binary-like, not edited manually).
96+
- `fontlab7/srcdocs/`:
97+
- `docs/`: Hand-written Markdown pages to be included directly in the site.
98+
- `mkdocs/`: Auto-generated Markdown from pydocmk2; input for MkDocs.
99+
- `post/`: Optional Markdown files appended to the generated pages to enhance API docs with human-authored commentary.
100+
- `fontlab7/theme/`:
101+
- `404.html`: Theme override for the not-found page.
102+
- `style/fontlab_pyapi.css`: Custom CSS to tailor typography and header/search styling.
103+
104+
### pythonqt/ (PythonQt API docs source)
105+
106+
- `pythonqt/mkdocs.yml`: MkDocs site configuration for PythonQt API docs; outputs to `../docs/pythonqt`.
107+
- `pythonqt/pydocmk.yml`: pydocmk2 configuration for generating Markdown for Qt bindings (Qt, QtCore, QtGui, QtOpenGL, QtSvg, QtUiTools, QtXml, QtXmlPatterns, private).
108+
- `pythonqt/build/`:
109+
- `build_pythonqt_api_docs.command`: macOS helper script to open the `.vfpy` project and build PythonQt docs.
110+
- `build_pythonqt_api_docs.vfpy`: FontLab project file used to drive generation.
111+
- `pythonqt/srcdocs/`:
112+
- `docs/`: Hand-written Markdown pages included directly in the PythonQt docs.
113+
- `mkdocs/`: Auto-generated Markdown produced by pydocmk2; input to MkDocs.
114+
- `pythonqt/theme/`:
115+
- `style/fontlab_pyapi.css`: Custom CSS (same purpose as in `fontlab7/theme/style/`).
116+
117+
## Notes on Generated Content
118+
119+
- Most files under `docs/` are generated; do not edit by hand. Their source content lives in:
120+
- `fontlab7/srcdocs/mkdocs/` (generated Markdown)
121+
- `fontlab7/srcdocs/docs/` and `fontlab7/srcdocs/post/` (human-authored additions)
122+
- `pythonqt/srcdocs/mkdocs/` and `pythonqt/srcdocs/docs/` for PythonQt
123+
- The generated HTML files map to the navigation declared in the respective `mkdocs.yml` files.
124+
125+
## Regeneration Commands (informational)
126+
127+
- Install pydocmk2 for Python 2.7, per README:
128+
- `python2 -m pip install --user --upgrade git+https://github.com/twardoch/pydocmk2`
129+
- Build FontLab 7 API docs:
130+
- Open `fontlab7/build/build_fontlab7_api_docs.vfpy` in FontLab 7 and wait for Markdown generation to `fontlab7/srcdocs/mkdocs/`.
131+
- `cd fontlab7/build && python2 -m mkdocs build -v -f ../mkdocs.yml --dirty`
132+
- Build PythonQt API docs (similar):
133+
- `cd pythonqt/build && python2 -m mkdocs build -v -f ../mkdocs.yml --dirty`
134+

‎REVIEW/TODO-cla.md‎

Lines changed: 173 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,173 @@
1+
---
2+
title: Repository Improvement Plan (CLA Review)
3+
this_file: REVIEW/TODO-cla.md
4+
---
5+
6+
# Improvement Plan and Proposals
7+
8+
Context: This repo builds and hosts documentation for the FontLab 7 Python API and PythonQt using pydocmk2 (Python 2.7) and MkDocs Material. Below is a concrete, example-driven plan to improve maintainability, reproducibility, and contributor experience. No code changes are performed here; this document proposes them.
9+
10+
## Goals
11+
12+
- Reliable, one-command builds for both `fontlab7` and `pythonqt` docs.
13+
- Clear separation of sources vs. generated artefacts; deterministic outputs.
14+
- Modernized build path and CI to publish to GitHub Pages automatically.
15+
- Contributor-friendly docs and CLA flow with examples and templates.
16+
17+
## Observations
18+
19+
- Generated HTML is committed in `docs/` and is large; rebuild steps require Python 2.7 and local FontLab to produce sources for MkDocs.
20+
- Two parallel doc trees (`fontlab7/`, `pythonqt/`) have near-duplicate configuration and theme customizations.
21+
- `README.md` focuses on manual builds; there’s no automated build script or CI.
22+
- No `CONTRIBUTING.md`, PR/issue templates, or clear “generated vs. source” guidance.
23+
24+
## Proposed Improvements (with examples)
25+
26+
1) Build Automation (single entry point)
27+
- Add a top-level task runner so contributors don’t memorize commands.
28+
- Example Makefile snippet:
29+
```make
30+
.PHONY: build build-fontlab7 build-pythonqt serve clean
31+
32+
build: build-fontlab7 build-pythonqt
33+
34+
build-fontlab7:
35+
cd fontlab7/build && python2 -m mkdocs build -v -f ../mkdocs.yml --dirty
36+
37+
build-pythonqt:
38+
cd pythonqt/build && python2 -m mkdocs build -v -f ../mkdocs.yml --dirty
39+
40+
serve:
41+
cd fontlab7 && python2 -m mkdocs serve -f mkdocs.yml
42+
43+
clean:
44+
rm -rf docs/ docs/pythonqt/
45+
```
46+
47+
2) Reproducible Environments
48+
- Document pinned versions for MkDocs and theme used with Python 2 runtime (or ship a container).
49+
- Example: `Dockerfile` to encapsulate the Python 2 toolchain and mkdocs build:
50+
```Dockerfile
51+
FROM python:2.7-slim
52+
RUN pip install --no-cache-dir git+https://github.com/twardoch/pydocmk2 mkdocs==0.17.5 mkdocs-material==2.9.4
53+
WORKDIR /src
54+
CMD ["bash", "-lc", "cd fontlab7/build && python -m mkdocs build -f ../mkdocs.yml && cd ../../pythonqt/build && python -m mkdocs build -f ../mkdocs.yml"]
55+
```
56+
- Alternative: Prebuilt GH Actions setup using `actions/setup-python@v4` with a Python 2 toolchain (if available) or container job.
57+
58+
3) Generated Artefact Policy
59+
- Treat `docs/` as build output; either:
60+
- Keep committed only on a dedicated `gh-pages` branch (preferred), or
61+
- Continue committing to `main`, but clarify that `docs/` is generated and add regeneration policy.
62+
- Example README blurb:
63+
> The `docs/` directory is generated by MkDocs; do not edit HTML directly. Edit sources under `fontlab7/srcdocs` or `pythonqt/srcdocs`, then rebuild.
64+
65+
4) CI/CD for Publishing (GitHub Pages)
66+
- Add a workflow that builds and deploys on tag or main branch updates.
67+
- Example `.github/workflows/docs.yml` (container-based for Python 2):
68+
```yaml
69+
name: Build and Deploy Docs
70+
on:
71+
push:
72+
branches: [ main ]
73+
tags: [ 'v*' ]
74+
jobs:
75+
build:
76+
runs-on: ubuntu-latest
77+
container: python:2.7-slim
78+
steps:
79+
- uses: actions/checkout@v3
80+
- run: pip install git+https://github.com/twardoch/pydocmk2 mkdocs==0.17.5 mkdocs-material==2.9.4
81+
- run: cd fontlab7/build && python -m mkdocs build -f ../mkdocs.yml
82+
- run: cd pythonqt/build && python -m mkdocs build -f ../mkdocs.yml || true
83+
- uses: actions/upload-pages-artifact@v3
84+
with:
85+
path: docs
86+
deploy:
87+
needs: build
88+
permissions:
89+
pages: write
90+
id-token: write
91+
environment:
92+
name: github-pages
93+
url: ${{ steps.deployment.outputs.page_url }}
94+
runs-on: ubuntu-latest
95+
steps:
96+
- id: deployment
97+
uses: actions/deploy-pages@v4
98+
```
99+
- Note: The PythonQt build may be optional if its sources require a FontLab-installed environment. The MkDocs phase can still publish existing generated content.
100+
101+
5) Deduplicate and Centralize Theme/Config
102+
- Extract shared MkDocs settings (extensions, analytics, palette, logo, extra_css) into a common YAML and anchor-merge them in both `mkdocs.yml` files.
103+
- Example pattern (YAML anchors):
104+
```yaml
105+
# common.yml
106+
x-theme: &theme
107+
name: material
108+
logo: https://.../icon-fontlab-7.png
109+
palette: { primary: indigo }
110+
x-markdown: &markdown_ext
111+
- attr_list
112+
- def_list
113+
- tables
114+
- pymdownx.superfences: { highlight_code: true }
115+
```
116+
- Then in `fontlab7/mkdocs.yml` and `pythonqt/mkdocs.yml`, import or copy-with-anchors to avoid drift.
117+
118+
6) Clear Source Structure and Examples
119+
- Add short `README.md` files inside `fontlab7/srcdocs/` and `pythonqt/srcdocs/` describing:
120+
- Where to add hand-written docs (`docs/`), and how `pre/` and `post/` files work.
121+
- Concrete examples (e.g., `typerig.core.objects.cubicbezier.md` → pre/post pages) with a before/after snippet.
122+
- Example guidance snippet:
123+
```md
124+
To prepend content to an API page generated as `fontgate.fgGlyph.md`, create `srcdocs/pre/fontgate.fgGlyph.md` with an intro, usage example, and notes.
125+
```
126+
127+
7) Contributor Experience and CLA Flow
128+
- Add `CONTRIBUTING.md` with prerequisites, build commands, and CLA requirement.
129+
- Add issue/PR templates to encourage adding `pre/`/`post/` docs and repro steps for build issues.
130+
- Link CLA prominently in `README.md` and `CONTRIBUTING.md`.
131+
132+
8) Modernization Strategy (medium-term)
133+
- Python 2.7 is EOL; plan a migration path:
134+
- Verify pydocmk2 compatibility with Python 3 (or alternatives like `pdoc`, `pdoc3`, `sphinx`, or mkdocstrings).
135+
- Prototype generating Markdown for a subset of modules with Python 3 toolchain; compare output.
136+
- If FontLab export step is the blocker, consider exporting intermediate JSON or reStructuredText and converting to Markdown with a Python 3 tool.
137+
138+
9) Housekeeping
139+
- Ensure `.gitignore` excludes local caches and temporary files (e.g., `*.vfpyc`, `.DS_Store`, `site/`, `.pytest_cache/`).
140+
- Add `CODE_OF_CONDUCT.md` and `SECURITY.md` for standardization.
141+
- Add `mkdocs serve` instructions and a port note for local preview.
142+
143+
## Phased Plan
144+
145+
- Phase 0: Document status
146+
- Clarify in `README.md` what is generated vs. source; add regeneration and publishing policy.
147+
148+
- Phase 1: Automation
149+
- Add Makefile and a minimal CI workflow to build and publish existing docs to GitHub Pages.
150+
- Keep PythonQt build optional if data is not available in CI.
151+
152+
- Phase 2: Config hygiene
153+
- Deduplicate MkDocs config (anchors or a shared snippet). Consolidate custom CSS in a single source and symlink or copy as needed.
154+
155+
- Phase 3: Contributor enablement
156+
- Add `CONTRIBUTING.md`, templates, and `srcdocs/` READMEs with concrete examples.
157+
158+
- Phase 4: Modernization prototype
159+
- Spike a Python 3 build path for one module group using mkdocstrings or pdoc. Compare fidelity and decide on migration roadmap.
160+
161+
## Risks and Mitigations
162+
163+
- Python 2 toolchain availability: Use containerized builds to ensure longevity.
164+
- FontLab dependency for generation: Capture generated Markdown in repo (not just HTML) to reduce reliance on local FontLab for every rebuild; document when regeneration is necessary.
165+
- CI stability: Pin MkDocs and theme versions; test on a branch before switching Pages to Actions.
166+
167+
## Success Criteria
168+
169+
- `make build` (or one equivalent command) produces the same `docs/` artefacts deterministically on a clean machine.
170+
- GitHub Pages deploys automatically on merges to `main`.
171+
- Contributors can add/modify `pre/` and `post/` docs with clear guidance and examples.
172+
- Reduced configuration drift between `fontlab7` and `pythonqt` trees.
173+

0 commit comments

Comments
 (0)