{"id":38054217,"url":"https://github.com/40ants/docs-builder","last_synced_at":"2026-01-16T20:21:43.935Z","repository":{"id":62113247,"uuid":"336501721","full_name":"40ants/docs-builder","owner":"40ants","description":"A generic documentation builder for Common Lisp projects.","archived":false,"fork":false,"pushed_at":"2025-05-04T14:54:13.000Z","size":245,"stargazers_count":3,"open_issues_count":0,"forks_count":0,"subscribers_count":2,"default_branch":"master","last_synced_at":"2025-05-04T15:36:33.356Z","etag":null,"topics":["common-lisp","documentation-builder"],"latest_commit_sha":null,"homepage":"https://40ants.com/docs-builder/","language":"Common Lisp","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"unlicense","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/40ants.png","metadata":{"files":{"readme":"README.md","changelog":"ChangeLog.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2021-02-06T09:33:21.000Z","updated_at":"2024-12-14T11:46:09.000Z","dependencies_parsed_at":"2024-12-14T09:22:56.260Z","dependency_job_id":"27445c57-c380-4b13-bcda-fce0b96d113f","html_url":"https://github.com/40ants/docs-builder","commit_stats":null,"previous_names":[],"tags_count":10,"template":false,"template_full_name":null,"purl":"pkg:github/40ants/docs-builder","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/40ants%2Fdocs-builder","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/40ants%2Fdocs-builder/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/40ants%2Fdocs-builder/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/40ants%2Fdocs-builder/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/40ants","download_url":"https://codeload.github.com/40ants/docs-builder/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/40ants%2Fdocs-builder/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28482267,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-16T11:59:17.896Z","status":"ssl_error","status_checked_at":"2026-01-16T11:55:55.838Z","response_time":107,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["common-lisp","documentation-builder"],"created_at":"2026-01-16T20:21:43.060Z","updated_at":"2026-01-16T20:21:43.904Z","avatar_url":"https://github.com/40ants.png","language":"Common Lisp","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003ca id=\"x-28DOCS-BUILDER-3A-40README-2040ANTS-DOC-2FLOCATIVES-3ASECTION-29\"\u003e\u003c/a\u003e\n\n# Common Lisp Docs Builder\n\n[![](https://github-actions.40ants.com/40ants/docs-builder/matrix.svg)][100b]\n\n\u003ca id=\"docs-builder-asdf-system-details\"\u003e\u003c/a\u003e\n\n## DOCS-BUILDER ASDF System Details\n\n* Description: A meta documentation builder for Common Lisp projects.\n* Licence: Unlicense\n* Author: Alexander Artemenko\n* Homepage: [https://40ants.com/docs-builder][3993]\n* Bug tracker: [https://github.com/40ants/docs-builder/issues][7d71]\n* Source control: [GIT][843b]\n* Depends on: [40ants-doc][2c00], [alexandria][8236], [docs-config][ce67], [log4cl][7f8b], [uiop][5274]\n\nThis system is a generic documentation builder for Common Lisp Systems.\nIt able to generate `HTML` documentation for specified `ASDF` system.\n\nThe idea is to use `docs-builder` as an universal `HTML` documentation builders\nwhich can be used in a continuous integration pipeline. For example, it is\nused inside [build-docs][0ebc] GitHub action, which can be\nused to build docs update gh-pages for any Common Lisp library (if it is uses\ndocumentation generator supported by `docs-builder`).\n\nCurrently Docs Builder supports only [`40ants-doc`][a2c7], [MGL-PAX][7927]\nand [Geneva][05ae], but it\ncan be extended to support other documentation builders, covered by examples in here:\n[cl-doc-systems.github.io][8884].\n\n\u003ca id=\"x-28DOCS-BUILDER-2FDOCS-3A-3A-40USAGE-2040ANTS-DOC-2FLOCATIVES-3ASECTION-29\"\u003e\u003c/a\u003e\n\n## Usage\n\nDocumentation can be built in a few ways: from the lisp `REPL`, command-line and\nusing the [GitHub action][0ebc].\n\n\u003ca id=\"x-28DOCS-BUILDER-2FDOCS-3A-3A-40REPL-USAGE-2040ANTS-DOC-2FLOCATIVES-3ASECTION-29\"\u003e\u003c/a\u003e\n\n### REPL\n\nFrom the `REPL`, you need first to call a [`docs-builder:build`][febf] function:\n\n\u003ca id=\"x-28DOCS-BUILDER-3ABUILD-20FUNCTION-29\"\u003e\u003c/a\u003e\n\n#### [function](13ba) `docs-builder:build` system \u0026rest rest \u0026key (error-on-warnings t) \u0026allow-other-keys\n\nBuilds `HTML` documentation for `ASDF` system and returns absolute path to the dir with docs.\n\nInside, it will try to guess which documentation builder should be used:\n\n\u003ca id=\"x-28DOCS-BUILDER-2FGUESSER-3AGUESS-BUILDER-20GENERIC-FUNCTION-29\"\u003e\u003c/a\u003e\n\n#### [generic-function](74f3) `docs-builder/guesser:guess-builder` system\n\nReturns a builder object which can be passed to the [`docs-builder/builder:build`][9de0] generic-function along with system.\n\nThe builder type is guessed using different euristics which depends on a documentation system.\n\nIf you want to add support for a new documentation generator, use [`defguesser`][3453] macro.\n\nThen it will pass the builder object and `ASDF` system to the [`docs-builder/builder:build`][9de0] generic-function:\n\n\u003ca id=\"x-28DOCS-BUILDER-2FBUILDER-3ABUILD-20GENERIC-FUNCTION-29\"\u003e\u003c/a\u003e\n\n#### [generic-function](18b9) `docs-builder/builder:build` builder system \u0026key local root-sections \u0026allow-other-keys\n\nBuilds `HTML` documentation for `ASDF` system and returns absolute path to the dir with docs.\n\nHere is an example how to build documentation for `:docs-builder` `ASDF` system:\n\n```lisp\nCL-USER\u003e (docs-builder:build :docs-builder)\n \u003cINFO\u003e [02:12:00] docs-builder/core core.lisp (build :before system) -\n  Building docs for system #\u003cPACKAGE-INFERRED-SYSTEM \"docs-builder\"\u003e found at /Users/art/projects/docs-builder/\n \u003cINFO\u003e [02:12:00] docs-builder/builders/mgl-pax/builder builder.lisp (build builder system) -\n  Building docs in \"/Users/art/projects/docs-builder/docs/build/\" dir\n#P\"/Users/art/projects/docs-builder/docs/build/\"\n```\n\u003ca id=\"x-28DOCS-BUILDER-2FDOCS-3A-3A-40COMMAND-LINE-USAGE-2040ANTS-DOC-2FLOCATIVES-3ASECTION-29\"\u003e\u003c/a\u003e\n\n### Command-line\n\nYou can use builder from command-line. To do this, first install it using [Roswell][795a]:\n\n```bash\n# Note, we need to install this patched mgl-pax\n# first, to be able to load docs-builder.\n# This step in necessary until this pull\n# will be merged:\n# https://github.com/melisgl/mgl-pax/pull/8\n\n$ ros install 40ants/doc\n\n$ ros install 40ants/docs-builder\n```\nHere we call it to build documentation for \"docs-builder\" `ASDF` system:\n\n```\n$ build-docs docs-builder\n \u003cINFO\u003e [02:26:32] docs-builder/main main.lisp (main) -\n  Quickloading system \"docs-builder\"\n \u003cINFO\u003e [02:26:34] docs-builder/core core.lisp (build :before system) -\n  Building docs for system #\u003cPACKAGE-INFERRED-SYSTEM \"docs-builder\"\u003e found at /Users/art/projects/docs-builder/\n \u003cINFO\u003e [02:26:34] docs-builder/builders/mgl-pax/builder builder.lisp (build builder system) -\n  Building docs in \"/Users/art/projects/docs-builder/docs/build/\" dir\nScan was called 2146 times.\n```\n\u003ca id=\"x-28DOCS-BUILDER-2FDOCS-3A-3A-40GITHUB-ACTION-USAGE-2040ANTS-DOC-2FLOCATIVES-3ASECTION-29\"\u003e\u003c/a\u003e\n\n### GitHub Action\n\nIf you host your project on the GitHub, then the most easy way to build and host documentation\nwould be to use [Github Pages][9f4c].\n\nTo build docs and update the site, create a file `.github/workflows/docs.yml` with a content like this:\n\n```yaml\nname: 'Docs'\n\non:\n  # This will run tests on pushes\n  # to master branch and every monday:\n  push:\n    branches:\n      - 'main'\n      - 'master'\n  schedule:\n    - cron:  '0 10 * * 1'\n\njobs:\n  build-docs:\n    runs-on: ubuntu-latest\n    \n    env:\n      LISP: sbcl-bin\n\n    steps:\n      - uses: actions/checkout@v1\n      - uses: 40ants/setup-lisp@v1\n      - uses: 40ants/build-docs@v1\n        with:\n          asdf-system: cl-info\n```\nYou'll find more info in [the action's documentation][0ebc].\n\n\u003ca id=\"x-28DOCS-BUILDER-2FDOCS-3A-3A-40ADDITIONAL-PARAMS-2040ANTS-DOC-2FLOCATIVES-3ASECTION-29\"\u003e\u003c/a\u003e\n\n### Additional Params\n\nYou can customize a builder by defining a method for this generic function:\n\n\u003ca id=\"x-28DOCS-CONFIG-3ADOCS-CONFIG-20GENERIC-FUNCTION-29\"\u003e\u003c/a\u003e\n\n#### [generic-function](676f) `docs-config:docs-config` asdf-system\n\nShould return a plist which will be passed as keyword\narguments to the documentation builder when building\ndocs for a given asdf-system.\n\nImplement a method, `EQL` specialized on a concrete `ASDF` system.\n\nHere is a typical method I use for my own libraries to set\na custom theme for [`40ants-doc`][a2c7] system:\n\n```lisp\n(defmethod docs-config ((system (eql (asdf:registered-system \"cl-info\"))))\n  ;; 40ANTS-DOC-THEME-40ANTS system will bring\n  ;; as dependency a full 40ANTS-DOC but we don't want\n  ;; unnecessary dependencies here:\n  (uiop:symbol-call :ql :quickload :40ants-doc-theme-40ants)\n  (list :theme\n        (find-symbol \"40ANTS-THEME\"\n                     (find-package \"40ANTS-DOC-THEME-40ANTS\"))))\n```\nTry to load additional dependencies inside the method. This users of your\nlibrary will not download dependencies needed only for building documentation.\n\nFor some special cases it might be useful to return a special key `DYNAMIC-BINDINGS`.\nThis could be useful, for configuring some custom extensions like it did with\ninteractive demos for the [Weblocks][8d16]. Here is how\na method looks like when I configure Weblocks documentation builder:\n\n```\n(defmethod docs-config ((system (eql (asdf:registered-system \"weblocks\"))))\n  ;; ...\n  (list :theme\n        (find-symbol \"40ANTS-THEME\"\n                     (find-package \"40ANTS-DOC-THEME-40ANTS\"))\n        :dynamic-bindings (list (cons 'weblocks/doc/example:*server-url*\n                                      ;; When local examples server is running,\n                                      ;; we'll be using it instead of production:\n                                      (unless weblocks/doc/example::*port*\n                                        \"http://examples.40ants.com/\"))))\n```\n\u003ca id=\"x-28DOCS-BUILDER-2FDOCS-3A-3A-40ROADMAP-2040ANTS-DOC-2FLOCATIVES-3ASECTION-29\"\u003e\u003c/a\u003e\n\n## Roadmap\n\n* Use [eazy-documentation][f9f7] as default fallback\n  when no other builder was guessed.\n* Support other documentation generators, collected at https://cl-doc-systems.github.io/\n* Add ability to put a configuration file into the reporitory, for fine-tunning the builder.\n\n\n[0ebc]: https://40ants.com/build-docs\n[a2c7]: https://40ants.com/doc/#x-28-23A-28-2810-29-20BASE-CHAR-20-2E-20-2240ants-doc-22-29-20ASDF-2FSYSTEM-3ASYSTEM-29\n[3993]: https://40ants.com/docs-builder\n[9de0]: https://40ants.com/docs-builder/#x-28DOCS-BUILDER-2FBUILDER-3ABUILD-20GENERIC-FUNCTION-29\n[3453]: https://40ants.com/docs-builder/#x-28DOCS-BUILDER-2FGUESSER-3ADEFGUESSER-20-2840ANTS-DOC-2FLOCATIVES-3AMACRO-29-29\n[febf]: https://40ants.com/docs-builder/#x-28DOCS-BUILDER-3ABUILD-20FUNCTION-29\n[8d16]: https://40ants.com/weblocks/\n[8884]: https://cl-doc-systems.github.io/\n[843b]: https://github.com/40ants/docs-builder\n[100b]: https://github.com/40ants/docs-builder/actions\n[18b9]: https://github.com/40ants/docs-builder/blob/c5f5a252a3bb8b1ba43a27f684137ce8b1b778aa/src/builder.lisp#L10\n[676f]: https://github.com/40ants/docs-builder/blob/c5f5a252a3bb8b1ba43a27f684137ce8b1b778aa/src/config.lisp#L9\n[13ba]: https://github.com/40ants/docs-builder/blob/c5f5a252a3bb8b1ba43a27f684137ce8b1b778aa/src/core.lisp#L29\n[74f3]: https://github.com/40ants/docs-builder/blob/c5f5a252a3bb8b1ba43a27f684137ce8b1b778aa/src/guesser.lisp#L14\n[7d71]: https://github.com/40ants/docs-builder/issues\n[7927]: https://github.com/melisgl/mgl-pax\n[795a]: https://github.com/roswell/roswell\n[f9f7]: https://guicho271828.github.io/eazy-documentation/\n[05ae]: https://inters.co/geneva/open-geneva.html\n[9f4c]: https://pages.github.com/\n[2c00]: https://quickdocs.org/40ants-doc\n[8236]: https://quickdocs.org/alexandria\n[ce67]: https://quickdocs.org/docs-config\n[7f8b]: https://quickdocs.org/log4cl\n[5274]: https://quickdocs.org/uiop\n\n* * *\n###### [generated by [40ANTS-DOC](https://40ants.com/doc/)]\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2F40ants%2Fdocs-builder","html_url":"https://awesome.ecosyste.ms/projects/github.com%2F40ants%2Fdocs-builder","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2F40ants%2Fdocs-builder/lists"}