HB Book - Literate Erlang Docs #482
Closed
Conversation
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
- Add mdbook-based documentation framework with 158+ Erlang module docs - Configure mdbook with custom port 3471 and disabled chapter numbering - Set build directory to 'dist' to avoid confusion with source structure - Add gitignore entry to exclude generated documentation files - Include custom CSS and JavaScript for enhanced documentation experience - Organize modules by functional categories: Arweave Foundation, Device Framework, Codec Modules, Core Services, and HyperBEAM Core
These are generated artifacts that duplicate source code and should not be committed. The build process now generates them on-demand.
- Add entries to .gitignore for generated literate Erlang documentation files - Adjust custom CSS to fix excessive heading margins in generated documentation - Remove outdated copy functionality section from introduction.md
… layout - Set margin-top for h2 and h3 elements to 0 to reduce excessive spacing in generated documentation.
- Change title from "HyperBEAM Literate Documentation" to "HyperBEAM Book" in book.toml and README.md. - Adjust heading margins for h2 and h3 elements in custom.css for improved layout. - Add styling for search input and results in custom.css to enhance user experience.
- Change workflow name to "Build & Deploy mkdocs Documentation". - Update trigger branches for pull requests and pushes to include `docs/deploy` and `docs/deploy-test`. - Exclude `docs/book/**` from triggering the workflow. - Modify deployment conditions to handle production and preview deployments based on the branch. - Rename build step to "Build mkdocs Documentation" for clarity.
- Modify workflow triggers to include changes in source code and mdBook configuration files. - Remove outdated references to `docs/book/**` and streamline the deployment process. - Ensure the workflow is set to trigger on relevant changes for improved documentation management.
- Add new CSS file `theme/highlight.css` for improved syntax highlighting styles. - Update `book.toml` to include the new CSS file alongside the existing custom styles. - Introduce `highlight.js` for enhanced code highlighting functionality in documentation.
- Introduce `erlang.min.js` for Erlang grammar in Highlight.js to enhance code highlighting in documentation. - Update `highlight.js` to include the new Erlang language support, improving the overall syntax highlighting capabilities.
- Update `build-literate-erlang.sh` to improve the extraction of module and function documentation by preserving paragraph breaks. - Introduce a new function `write_code_with_inline_comments` to handle inline comments in Erlang code, ensuring proper formatting and structure in the output. - Refactor existing code to enhance readability and maintainability while processing Erlang documentation.
- Change authors in `book.toml` to "HyperBEAM Core Team". - Set default theme to "rust" in `custom.js` if no theme is stored, improving user experience with theme management. - Introduce `setDefaultTheme` function to manage theme preferences effectively.
- Introduce `build-and-serve.sh` to automate the generation and local serving of literate documentation. - Add `build-literate-erlang-js.sh` for a comprehensive Erlang documentation generation using JavaScript. - Update `build-literate-erlang.sh` to improve documentation extraction and formatting. - Create `erlang-literate-parser.js` for enhanced parsing of Erlang files, supporting various comment types and annotations. - Add `README.md` in the book source directory to provide an overview of the generated documentation. - Remove outdated `erlang.min.js` and `highlight.js` files to streamline the documentation theme.
- Introduce `collectParamTagsBeforeSpec` method to gather parameter and return tags before specifications, improving documentation accuracy. - Modify `processFunctionBody` to handle inline documentation tags more effectively, ensuring proper formatting in generated output. - Update `cleanDocumentation` and `formatPreContent` methods for better handling of structured content and documentation formatting. - Revise `introduction.md` and `SUMMARY.md` to reflect updated terminology and improve organization of documentation sections.
…and documentation handling - Update return processing to utilize `splitReturnsIntoOutcomes` and `formatReturnsText` for better output formatting. - Enhance handling of continuation lines in return and parameter sections to maintain clarity in documentation. - Introduce `reflowNumberedLists` method to ensure proper formatting of numbered lists in generated documentation.
…cumentation handling - Introduce character codes and string constants for faster comparisons and reduced memory allocations. - Optimize regex patterns for performance and clarity in parsing Erlang files. - Enhance the reset method to initialize module information with default values. - Update function processing to utilize constants for improved readability and maintainability. - Revise documentation generation methods to ensure consistent formatting and structure in output.
- Update outdated scripts: `build-all.sh`, `build-and-serve.sh`, `build-literate-erlang.sh`, and `build-literate-erlang-js.sh`. - These scripts have been superseded by more efficient implementations, streamlining the documentation generation process. - Ensure the codebase is cleaner and more maintainable by removing legacy files.
- Replace deprecated `build-literate-erlang.sh` with `generate-literate-docs.sh` in the GitHub Actions workflow. - Ensure the workflow reflects the latest script for generating literate documentation, maintaining consistency in the build process.
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Summary
Creates a dedicated GitHub Actions workflow to automatically build and deploy the mdBook literate documentation to ArNS when changes are pushed to the
edgebranch.Features
build-literate-erlang.shto generate fresh.erl.mdfiles from sourcebook_hyperbeam.arweave.netvia ArNS)Workflow Details
edgebranch pushes affectingsrc/**, mdBook config, or build scriptssrc/filespermaweb-deployto deploy to ArNS withhyperbeamname andbookundernameUpdated Workflows
build-deploy-mdbook.yml- Dedicated mdBook workflow triggered by source changesbuild-deploy-docs.yml- Now mkdocs-only, excludesdocs/book/**, usesdocs/deploybranches with conditional ArNS deploymentBenefits
This ensures
book_hyperbeam.arweave.netreflects the latest codebase state whenever developers push changes toedge.