|
| 1 | +# PyBuilder Documentation Site — Project Instructions |
| 2 | + |
| 3 | +## Overview |
| 4 | + |
| 5 | +This is the official documentation website for [PyBuilder](https://pybuilder.io), |
| 6 | +hosted on GitHub Pages. It is a Jekyll static site. The source lives on the `source` |
| 7 | +branch; the `master` branch contains only the built output deployed by CI. |
| 8 | + |
| 9 | +Repository: `pybuilder/pybuilder.github.io` (origin, not a fork). |
| 10 | + |
| 11 | +## Branch Model |
| 12 | + |
| 13 | +- **`source`** — all development happens here. This is the default working branch. |
| 14 | +- **`master`** — auto-deployed built site. Never edit or push to `master` directly. |
| 15 | +- **`plugin_doc_gen`** — WIP branch for plugin documentation rework. |
| 16 | +- **`bootstrap_4`** — stale Bootstrap 4 migration branch. |
| 17 | + |
| 18 | +PRs target `source`. The CI deploys to `master` on push to `source`. |
| 19 | + |
| 20 | +## Site Structure |
| 21 | + |
| 22 | +``` |
| 23 | +_config.yml — primary Jekyll configuration |
| 24 | +_config-prod.yml — production URL overlay (https://pybuilder.io) |
| 25 | +Gemfile — Ruby dependencies (Jekyll 4.x, plugins, html-proofer) |
| 26 | +build.sh — CI build script (build, validate, rebuild with prod config) |
| 27 | +CNAME — custom domain (pybuilder.io) |
| 28 | +
|
| 29 | +_layouts/ |
| 30 | + default.html — base layout (header, container, footer) |
| 31 | + documentation.html — two-column layout with auto-generated ToC sidebar |
| 32 | + post.html — blog post layout with author metadata |
| 33 | +
|
| 34 | +_includes/layout/ |
| 35 | + metaAndStyles.html — Google Analytics, meta tags, CSS imports |
| 36 | + header.html — navbar with navigation dropdowns |
| 37 | + footer.html — links, scripts, JS imports |
| 38 | +
|
| 39 | +_plugins/ |
| 40 | + pybuilder.rb — custom Liquid filters (abs/rel canonical URL helpers) |
| 41 | +
|
| 42 | +_data/ |
| 43 | + authors.yml — author profiles referenced by blog posts |
| 44 | +
|
| 45 | +documentation/ — all documentation pages (layout: documentation) |
| 46 | + index.md — documentation hub |
| 47 | + installation.md — installation guide |
| 48 | + tutorial.md — comprehensive tutorial (~590 lines, largest doc) |
| 49 | + manual.md — usage manual |
| 50 | + plugins.md — built-in plugin reference (~1100 lines) |
| 51 | + writing-plugins.md — plugin development guide |
| 52 | + publishing-plugins.md — how to publish plugins |
| 53 | + external-plugin-list.md — third-party plugins |
| 54 | + examples.md — example projects |
| 55 | + ide.md — IDE integration |
| 56 | + developing-pybuilder.md — contributing to PyBuilder core |
| 57 | +
|
| 58 | +articles/ — Jekyll collections directory |
| 59 | + _posts/ — blog posts (layout: post, author: <key from authors.yml>) |
| 60 | + _release-notes/ — release notes collection (v0.10.x through v0.13.x) |
| 61 | + _migration-guides/ — migration guides collection |
| 62 | +
|
| 63 | +css/ — custom stylesheets (styles.css, highlightjs.css, tabcontent.css) |
| 64 | +js/ — custom JS (highlight.pack.js, tabcontent.js, toc.js) |
| 65 | +img/ — logos, mascot, screenshots |
| 66 | +``` |
| 67 | + |
| 68 | +## Building Locally |
| 69 | + |
| 70 | +```bash |
| 71 | +# Install Ruby dependencies |
| 72 | +bundle install |
| 73 | + |
| 74 | +# Start development server with live reload |
| 75 | +bundle exec jekyll serve --watch |
| 76 | +# Browse to http://localhost:4000 |
| 77 | + |
| 78 | +# Full CI-equivalent build (build + htmlproofer + prod rebuild) |
| 79 | +./build.sh |
| 80 | +``` |
| 81 | + |
| 82 | +## CI / Deployment |
| 83 | + |
| 84 | +GitHub Actions workflow at `.github/workflows/pybuilder.github.io.yml`: |
| 85 | +1. Triggers on PRs to `source` and pushes to `source` |
| 86 | +2. Sets up Ruby 3.1, installs bundle dependencies |
| 87 | +3. Runs `build.sh`: |
| 88 | + - `jekyll build` (dev config) |
| 89 | + - `htmlproofer` validates links, scripts, images, OpenGraph, favicon |
| 90 | + - `jekyll build -c _config.yml,_config-prod.yml` (prod config with real URL) |
| 91 | +4. On push (not PR): deploys `_site/` to `master` branch |
| 92 | + |
| 93 | +## Content Conventions |
| 94 | + |
| 95 | +### Documentation Pages |
| 96 | + |
| 97 | +- Layout: `documentation` (provides auto-ToC sidebar) |
| 98 | +- Front matter: `layout: documentation`, `title: <Page Title>` |
| 99 | +- Use `{% link documentation/filename.md %}` for cross-references |
| 100 | +- Markdown with kramdown extensions (fenced code blocks, etc.) |
| 101 | + |
| 102 | +### Blog Posts |
| 103 | + |
| 104 | +- Location: `articles/_posts/YYYY-MM-DD-slug.md` |
| 105 | +- Layout: `post` |
| 106 | +- Front matter: `layout: post`, `title`, `author` (key from `_data/authors.yml`) |
| 107 | +- Optional: `update_date` for showing last-updated |
| 108 | + |
| 109 | +### Release Notes |
| 110 | + |
| 111 | +- Location: `articles/_release-notes/vX.Y.x.md` |
| 112 | +- One file per minor version series |
| 113 | + |
| 114 | +### Migration Guides |
| 115 | + |
| 116 | +- Location: `articles/_migration-guides/vX.Y.x-vA.B.C.md` |
| 117 | + |
| 118 | +## Technology Stack |
| 119 | + |
| 120 | +- Jekyll 4.x with kramdown (Markdown) and rouge (syntax highlighting) |
| 121 | +- Bootstrap 3.4.1 (CSS framework) |
| 122 | +- jQuery 3.4.1 |
| 123 | +- bootstrap-toc 0.4.1 (auto table of contents) |
| 124 | +- highlight.js (code highlighting) |
| 125 | +- lite-youtube 1.5.0 (lazy YouTube embeds) |
| 126 | +- Plugins: jekyll-sitemap, jekyll-paginate, jekyll-last-modified-at, |
| 127 | + jekyll-redirect-from, jekyll-seo-tag, jekyll-feed, jemoji, and others |
| 128 | + |
| 129 | +## Git Workflow |
| 130 | + |
| 131 | +This is an origin repo (not a fork). All changes go through PRs to `source`. |
| 132 | +Never push directly to `source` or `master`. |
| 133 | + |
| 134 | +## Content Editing |
| 135 | + |
| 136 | +- Keep documentation accurate with respect to the current PyBuilder release. |
| 137 | + Cross-reference the main PyBuilder repo at `../pybuilder/` for feature details. |
| 138 | +- Preserve existing front matter fields exactly. Do not add or remove fields |
| 139 | + unless intentionally changing page behavior. |
| 140 | +- Use the `{% link %}` Liquid tag for internal cross-references, never raw paths. |
| 141 | +- Do not reformat or rewrap existing paragraphs that you are not changing. |
| 142 | + Minimize diff noise. |
| 143 | + |
| 144 | +## Layouts and Includes |
| 145 | + |
| 146 | +- Bootstrap 3, not 4 or 5. The `bootstrap_4` migration was never completed. |
| 147 | + Do not upgrade Bootstrap unless explicitly asked. |
| 148 | +- Google Analytics tag is in `_includes/layout/metaAndStyles.html`. Do not |
| 149 | + modify or remove it. |
| 150 | +- Navigation structure is in `_includes/layout/header.html`. When adding new |
| 151 | + documentation pages, add a corresponding nav entry there and in |
| 152 | + `documentation/index.md`. |
| 153 | + |
| 154 | +## Adding New Documentation Pages |
| 155 | + |
| 156 | +1. Create the `.md` file in `documentation/` with front matter: |
| 157 | + ```yaml |
| 158 | + --- |
| 159 | + layout: documentation |
| 160 | + title: Your Page Title |
| 161 | + --- |
| 162 | + ``` |
| 163 | +2. Add a link in `documentation/index.md` under the appropriate section |
| 164 | +3. Add a navigation entry in `_includes/layout/header.html` |
| 165 | + |
| 166 | +## Adding Blog Posts |
| 167 | + |
| 168 | +1. Create `articles/_posts/YYYY-MM-DD-slug.md` with front matter: |
| 169 | + ```yaml |
| 170 | + --- |
| 171 | + layout: post |
| 172 | + title: "Post Title" |
| 173 | + author: arcivanov |
| 174 | + --- |
| 175 | + ``` |
| 176 | +2. Author key must exist in `_data/authors.yml` |
| 177 | + |
| 178 | +## Adding Release Notes |
| 179 | + |
| 180 | +1. If a file for the minor version series exists, append to it |
| 181 | +2. Otherwise create `articles/_release-notes/vX.Y.x.md` |
| 182 | +3. The release notes index auto-generates from the collection |
| 183 | + |
| 184 | +## Testing Changes |
| 185 | + |
| 186 | +- Always run `bundle exec jekyll build` to verify the site builds without errors |
| 187 | +- For thorough validation, run `./build.sh` which also checks links and images |
| 188 | + via htmlproofer |
| 189 | +- htmlproofer may fail on transient external link issues (429, timeouts). These |
| 190 | + are usually not your fault. Check if the link is actually broken before fixing. |
| 191 | + |
| 192 | +## Things to Avoid |
| 193 | + |
| 194 | +- Do not edit files on the `master` branch. It is auto-generated. |
| 195 | +- Do not add `Gemfile.lock` to version control (it is gitignored). |
| 196 | +- Do not modify vendored JS libraries (`highlight.pack.js`, jQuery, Bootstrap) |
| 197 | + unless upgrading them intentionally. |
| 198 | +- Do not remove or alter the `CNAME` file. |
| 199 | +- Do not change `_config.yml` pagination or permalink settings without |
| 200 | + understanding the URL impact on existing links and SEO. |
0 commit comments