Skip to content

Commit 96cd0fb

Browse files
twardochtwardoch
authored
Merge pull request #3 from fontlabcom/terragon/create-review-file-catalog
Add comprehensive file catalog and improvement proposals for FontLab Python docs
2 parents edf0b1c + 2d129e2 commit 96cd0fb

File tree

2 files changed

+746
-0
lines changed

2 files changed

+746
-0
lines changed

‎REVIEW/FILES-acla.md‎

Lines changed: 181 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,181 @@
1+
# FontLab Python API Documentation - File Catalog
2+
3+
## Repository Overview
4+
5+
This repository contains the **FontLab 7 Python API documentation** - a comprehensive documentation system for FontLab 7's Python APIs, including typerig, fontgate, fontlab, FL, and PythonQt modules. The documentation is built using MkDocs and pydocmk2 to generate static HTML documentation from Python docstrings.
6+
7+
## Filesystem Tree
8+
9+
```
10+
.
11+
├── LICENSE
12+
├── README.md
13+
├── REVIEW/
14+
├── docs/
15+
├── fontlab7/
16+
├── pythonqt/
17+
```
18+
19+
## Root Level Files
20+
21+
### LICENSE
22+
**Type**: Legal document
23+
**Purpose**: Apache License 2.0 - defines the legal terms for using and contributing to this documentation
24+
**Content**: Standard Apache 2.0 license text with copyright attribution to Fontlab Ltd.
25+
26+
### README.md
27+
**Type**: Documentation
28+
**Purpose**: Main project documentation and build instructions
29+
**Content**: Explains how to view, build, and contribute to the FontLab 7 Python API documentation. Includes setup instructions for Python 2.7, pydocmk2, and mkdocs.
30+
31+
---
32+
33+
## Main Directories
34+
35+
### docs/
36+
**Type**: Output directory
37+
**Purpose**: Generated static HTML documentation for public web hosting
38+
**Content**: Complete rendered documentation website hosted at fontlabcom.github.io
39+
40+
#### Core Documentation Files
41+
- **index.html**: Main landing page for the documentation
42+
- **404.html**: Custom 404 error page
43+
- **sitemap.xml**: SEO sitemap for search engines
44+
- **search/search_index.json**: Search index for documentation search functionality
45+
46+
#### API Documentation Structure
47+
- **FL.*.html**: FontLab 5 legacy API documentation (Anchor, Canvas, Component, Dialog, etc.)
48+
- **fontgate.*.html**: FontGate library API documentation (low-level font manipulation)
49+
- **fontlab.*.html**: FontLab 7 native API documentation (high-level application interface)
50+
- **typerig.*.html**: TypeRig library API documentation (community-developed utilities)
51+
52+
#### Static Assets
53+
- **assets/**: Web assets for the documentation site
54+
- **fonts/**: Web fonts (FontAwesome, Material Icons)
55+
- **images/**: Icons and favicon
56+
- **javascripts/**: Site functionality (search, navigation, localization)
57+
- **stylesheets/**: CSS styling for the documentation theme
58+
59+
---
60+
61+
### fontlab7/
62+
**Type**: Source directory
63+
**Purpose**: Main documentation build system for FontLab 7 APIs
64+
65+
#### build/
66+
**Purpose**: Build automation scripts
67+
- **build_fontlab7_api_docs.vfpy**: FontLab 7 script to generate markdown from Python docstrings
68+
- **build_fontlab7_api_docs.command**: macOS shell script to build HTML documentation
69+
- **build_fontlab7_api_docs.vfpyc**: Compiled version of the build script
70+
71+
#### Configuration Files
72+
- **mkdocs.yml**: MkDocs configuration for HTML generation (theme, navigation, plugins)
73+
- **pydocmk.yml**: pydocmk2 configuration for extracting Python docstrings and generating markdown
74+
75+
#### srcdocs/
76+
**Purpose**: Source documentation and generated markdown files
77+
78+
##### srcdocs/docs/
79+
- **index.md**: Homepage content for the documentation
80+
81+
##### srcdocs/mkdocs/
82+
**Purpose**: Auto-generated markdown files from Python docstrings
83+
**Content**: 300+ API reference files covering:
84+
- **typerig.*.md**: TypeRig library modules (core utilities, GUI widgets, proxy objects)
85+
- **fontgate.*.md**: FontGate library modules (font data structures, import/export options)
86+
- **fontlab.*.md**: FontLab 7 native modules (UI components, tools, data objects)
87+
- **FL.*.md**: Legacy FontLab 5 API compatibility layer
88+
89+
##### srcdocs/post/
90+
**Purpose**: Post-processing markdown additions (appended to auto-generated docs)
91+
- **fontlab.flWorkspace.md**: Additional documentation for workspace functionality
92+
93+
#### theme/
94+
**Purpose**: Custom MkDocs theme files
95+
- **404.html**: Custom 404 page template
96+
- **style/fontlab_pyapi.css**: Custom CSS styling for FontLab branding
97+
98+
---
99+
100+
### pythonqt/
101+
**Type**: Source directory
102+
**Purpose**: Documentation build system for PythonQt API (Qt bindings for FontLab)
103+
104+
#### build/
105+
- **build_pythonqt_api_docs.vfpy**: Build script for PythonQt documentation
106+
- **build_pythonqt_api_docs.command**: macOS build automation
107+
108+
#### Configuration Files
109+
- **mkdocs.yml**: MkDocs configuration for PythonQt docs (separate from main docs)
110+
- **pydocmk.yml**: pydocmk2 configuration for PythonQt modules
111+
112+
#### srcdocs/
113+
##### srcdocs/docs/
114+
- **index.md**: PythonQt documentation homepage
115+
- **PythonQt.QtCore.md**: Sample QtCore documentation
116+
117+
##### srcdocs/mkdocs/
118+
**Purpose**: Generated PythonQt API documentation
119+
**Content**: Qt framework bindings including:
120+
- **PythonQt.Qt.md**: Main Qt module
121+
- **PythonQt.QtCore.md**: Core Qt functionality
122+
- **PythonQt.QtGui.md**: GUI components
123+
- **PythonQt.QtOpenGL.md**: OpenGL integration
124+
- **PythonQt.QtSvg.md**: SVG support
125+
- **PythonQt.QtUiTools.md**: UI development tools
126+
- **PythonQt.QtXml.md**: XML parsing
127+
- **PythonQt.QtXmlPatterns.md**: XML pattern matching
128+
- **PythonQt.private.md**: Private Qt interfaces
129+
130+
#### theme/
131+
- **style/fontlab_pyapi.css**: Consistent styling with main documentation
132+
133+
---
134+
135+
### REVIEW/
136+
**Type**: Analysis directory (newly created)
137+
**Purpose**: Contains this file catalog and improvement recommendations
138+
**Content**: Documentation analysis and improvement proposals for the repository
139+
140+
---
141+
142+
## Key Technology Stack
143+
144+
### Documentation Generation
145+
- **pydocmk2**: Python docstring extraction and markdown generation
146+
- **MkDocs**: Static site generator with Material theme
147+
- **Python 2.7**: Required runtime for FontLab 7 integration
148+
149+
### API Coverage
150+
- **typerig**: Community-developed font manipulation utilities
151+
- **fontgate**: Low-level font data access and manipulation
152+
- **fontlab**: High-level FontLab 7 application interface
153+
- **FL**: Legacy FontLab 5 compatibility layer
154+
- **PythonQt**: Qt framework bindings for GUI development
155+
156+
### Web Technologies
157+
- **Material Design theme**: Modern, responsive documentation interface
158+
- **Search functionality**: Full-text search across all documentation
159+
- **Responsive design**: Mobile and desktop compatibility
160+
- **Syntax highlighting**: Code examples with proper highlighting
161+
162+
---
163+
164+
## File Organization Patterns
165+
166+
### Naming Conventions
167+
- Module files follow Python package structure: `package.module.submodule.md`
168+
- Generated files use consistent naming across all API libraries
169+
- Build scripts use descriptive names indicating their purpose
170+
171+
### Directory Structure
172+
- Clear separation between source (`srcdocs/`) and output (`docs/`)
173+
- Parallel structure for fontlab7 and pythonqt documentation systems
174+
- Dedicated build directories with automation scripts
175+
- Theme customization isolated in separate directories
176+
177+
### Documentation Hierarchy
178+
- Homepage and navigation structure defined in `mkdocs.yml`
179+
- API documentation organized by library and module hierarchy
180+
- Cross-references and linking maintained automatically
181+
- Search indexing covers all documentation content

0 commit comments

Comments
 (0)