// Moved from docs/src/build-and-tooling/DOCUMENTATION_README.adoc to docs/working/scratch/src/build-and-tooling/DOCUMENTATION_README.adoc on 2026-06-16 (docs reorg Phase 2) == StarForth Documentation System :toc: left :toc-title: Contents :toclevels: 3 xref:../README.adoc[← Back to Documentation Index] Welcome to the StarForth documentation system! This document explains how to generate, view, and contribute to the project documentation. === Quick Start ==== Generate All Documentation [source,bash] ---- make docs ---- This generates: * *AsciiDoc* - API documentation as AsciiDoc (docs/src/appendix/) ** Generated on-demand by `./scripts/generate-doxygen-appendix.sh` ** Periodically rebuilt by Jenkins ** Flat file structure, one file per source module ==== View Generated API Documentation [source,bash] ---- # Generate the AsciiDoc API documentation ./scripts/generate-doxygen-appendix.sh # View the index cat docs/src/appendix/index.adoc ---- The AsciiDoc files are in `docs/src/appendix/` with one file per source module. === Installation Requirements ==== Required (Core Functionality) [source,bash] ---- # Ubuntu/Debian sudo apt-get install doxygen graphviz # macOS brew install doxygen graphviz # Fedora/RHEL sudo dnf install doxygen graphviz ---- ==== Optional (Additional Formats) ===== For PDF Generation [source,bash] ---- # Ubuntu/Debian sudo apt-get install texlive-latex-base texlive-latex-extra # macOS brew install --cask mactex # Full TeX Live (~4GB) # Or for minimal install: brew install --cask basictex # Basic TeX (~100MB) # Fedora/RHEL sudo dnf install texlive-scheme-basic ---- ===== For AsciiDoc and Markdown [source,bash] ---- # All platforms sudo apt-get install pandoc # Debian/Ubuntu brew install pandoc # macOS sudo dnf install pandoc # Fedora/RHEL # AsciiDoc HTML rendering (optional) gem install asciidoctor ---- ==== Verify Installation [source,bash] ---- doxygen --version # Should be >= 1.9.0 dot -V # Graphviz, any recent version pandoc --version # Optional, for AsciiDoc/Markdown pdflatex --version # Optional, for PDF ---- === Documentation Targets [width="100%",cols="23%,40%,37%",options="header",] |=== |Target |Description |Requirements |`+make docs+` |Generate all formats |doxygen, graphviz (+ optional) |`+make docs-html+` |HTML only (fast) |doxygen, graphviz |`+make docs-pdf+` |PDF only |doxygen, graphviz, pdflatex |`+make docs-open+` |Generate HTML and open in browser |doxygen, graphviz |`+make docs-clean+` |Remove generated docs |none |=== === Documentation Structure .... docs/ ├── src/ # Source documentation (AsciiDoc) │ ├── appendix/ # Generated API documentation │ │ ├── index.adoc # API documentation index │ │ ├── vm.c.adoc # VM implementation documentation │ │ ├── vm.h.adoc # VM API header documentation │ │ └── ... # One file per source module │ │ │ ├── build-and-tooling/ │ │ ├── DOCUMENTATION_README.adoc # This file │ │ ├── DOXYGEN_STYLE_GUIDE.adoc # Doxygen comment style guide │ │ ├── ARCHITECTURE.adoc # System architecture │ │ └── ... │ │ │ └── README.adoc # Main documentation index │ └── (other documentation sources) .... === Adding Documentation to Code ==== Step 1: Read the Style Guide See DOXYGEN_STYLE_GUIDE.md for complete documentation standards. ==== Step 2: Use the Template Use examples/doxygen_example.h as a template showing all documentation styles. ==== Step 3: Document Your Code Example for a function: [source,c] ---- /** * @brief Push value onto data stack * * @details * Adds a value to the top of the data stack. Stack overflow * is checked and vm->error is set if stack is full. * * @param vm Pointer to VM instance * @param value Value to push * * @pre vm must be initialized * @pre vm->dsp < STACK_SIZE-1 * @post vm->dsp incremented by 1 * @post On error: vm->error is set * * @note This is a hot-path function - optimized for speed * @warning Always check vm->error after calling * * @see vm_pop() * @see vm_dup() * * @par Example: * @code * vm_push(&vm, 42); * if (vm.error) { * fprintf(stderr, "Stack overflow\n"); * } * @endcode */ void vm_push(VM *vm, cell_t value); ---- ==== Step 4: Check Documentation [source,bash] ---- make docs-html cat docs/src/appendix/doxygen_warnings.log ---- Fix any warnings about undocumented functions or parameters. === Documentation Coverage ==== Current Status Run `+make docs+` and check the summary for documentation coverage: * Target: 100% of public API headers * Current: TBD (run `+make docs+` to check) ==== Priority Files to Document [arabic] . *High Priority* (User-facing API): * `+include/vm.h+` - Core VM API * `+include/word_registry.h+` - Word registration * `+include/log.h+` - Logging API * `+include/io.h+` - I/O operations . *Medium Priority* (Developer API): * `+src/word_source/include/*.h+` - Word implementations * `+include/profiler.h+` - Performance profiling * `+include/vm_debug.h+` - Debugging support . *Low Priority* (Internal): * Private implementation files (*.c) * Test infrastructure headers === Integration with External Projects ==== Using StarForth Documentation in Your Project If your project uses StarForth, you can link to our documentation: [arabic] . Generate our docs: `+make docs+` . Reference our tag file: `+docs/src/appendix/starforth.tag+` . Add to your Doxyfile: + .... TAGFILES = path/to/starforth/docs/src/appendix/starforth.tag=https://your-docs-url/ .... === Continuous Integration ==== GitHub Actions Example [source,yaml] ---- name: Documentation on: [push, pull_request] jobs: docs: runs-on: ubuntu-latest steps: - uses: actions/checkout@v2 - name: Install dependencies run: | sudo apt-get update sudo apt-get install -y doxygen graphviz - name: Generate documentation run: make docs-html - name: Check for warnings run: | if [ -s docs/src/appendix/doxygen_warnings.log ]; then echo "Documentation warnings found:" cat docs/src/appendix/doxygen_warnings.log exit 1 fi - name: Deploy to GitHub Pages if: github.ref == 'refs/heads/master' uses: peaceiris/actions-gh-pages@v3 with: github_token: ${{ secrets.GITHUB_TOKEN }} publish_dir: ./docs/src/appendix/html ---- === Troubleshooting ==== Problem: "`doxygen: command not found`" *Solution:* Install doxygen (see Installation Requirements above) ==== Problem: "`dot: command not found`" *Solution:* Install graphviz package ==== Problem: "`pdflatex: command not found`" *Solution:* PDF generation is optional. Either: * Install TeX Live (see Installation Requirements) * Or use `+make docs-html+` for HTML only ==== Problem: No graphs/diagrams in documentation *Solution:* Install graphviz (`+sudo apt-get install graphviz+`) ==== Problem: Warnings about undocumented functions *Solution:* Add Doxygen comments to those functions (see Style Guide) ==== Problem: "`No such file or directory`" when opening docs *Solution:* Generate docs first: `+make docs-html+` ==== Problem: Pandoc errors for AsciiDoc/Markdown *Solution:* AsciiDoc/Markdown generation is optional. Either: * Install pandoc * Or ignore (HTML/PDF are sufficient) === Man Pages View generated man pages: [source,bash] ---- # List all man pages ls docs/src/appendix/man/ # View a specific page man -l docs/src/appendix/man/vm_init.3 # Install to system (optional) sudo cp docs/src/appendix/man/*.3 /usr/local/man/man3/ sudo mandb man vm_init # Now works without -l ---- === Contributing Documentation ==== Documentation Pull Requests When contributing code: [arabic] . *Document all public functions* - Use Doxygen comments . *Include examples* - Show how to use complex functions . *Check for warnings* - Run `+make docs-html+` and fix warnings . *Update existing docs* - If changing behavior, update comments ==== Documentation-Only Changes Documentation improvements are welcome! To contribute: [arabic] . Follow the DOXYGEN_STYLE_GUIDE.md . Test with `+make docs+` . Check for warnings in `+docs/src/appendix/doxygen_warnings.log+` . Submit PR with clear description of changes === Advanced Configuration ==== Customizing Documentation Edit `+Doxyfile+` to customize: * Project name/version: `+PROJECT_NAME+`, `+PROJECT_NUMBER+` * Input files: `+INPUT+`, `+FILE_PATTERNS+` * Output formats: `+GENERATE_HTML+`, `+GENERATE_LATEX+`, etc. * Diagram options: `+CALL_GRAPH+`, `+CALLER_GRAPH+` ==== Adding Custom Pages Create Markdown files in `+docs/+` and add to `+Doxyfile+`: .... INPUT = ... docs/MY_CUSTOM_PAGE.md .... ==== Theming HTML Output Customize appearance: .... HTML_EXTRA_STYLESHEET = docs/custom.css HTML_COLORSTYLE = AUTO_LIGHT .... === Documentation Formats ==== HTML * *Best for:* Interactive browsing, searching, navigation * *Location:* docs/src/appendix/html/index.html * *Features:* Hyperlinks, search, call graphs, file dependencies ==== PDF * *Best for:* Printing, offline reading, comprehensive reference * *Location:* docs/src/appendix/StarForth-API-Reference.pdf * *Features:* Table of contents, index, bookmarks ==== AsciiDoc * *Best for:* Technical writing, conversion to other formats * *Location:* docs/src/appendix/asciidoc/starforth-api.adoc * *Features:* Lightweight markup, easy to edit ==== Markdown * *Best for:* GitHub viewing, copy-paste into wikis * *Location:* docs/src/appendix/markdown/starforth-api.md * *Features:* GFM (GitHub-Flavored Markdown) ==== Man Pages * *Best for:* Unix command-line reference * *Location:* docs/src/appendix/man/*.3 * *Features:* Traditional man page format, system integration === Questions? * *Doxygen Manual:* https://www.doxygen.nl/manual/ * *Style Guide:* DOXYGEN_STYLE_GUIDE.md * *Example Code:* examples/doxygen_example.h * *Issues:* https://github.com/rajames440/StarForth/issues ''''' *Generated by the StarForth Documentation System* *Sniff-tested by Santino 🐕*