{"id":13993110,"url":"https://github.com/leanprover/doc-gen4","last_synced_at":"2025-10-31T15:30:41.099Z","repository":{"id":36992899,"uuid":"426835377","full_name":"leanprover/doc-gen4","owner":"leanprover","description":"Document Generator for Lean 4","archived":false,"fork":false,"pushed_at":"2025-02-03T08:37:21.000Z","size":817,"stargazers_count":78,"open_issues_count":23,"forks_count":42,"subscribers_count":14,"default_branch":"main","last_synced_at":"2025-02-03T09:34:55.431Z","etag":null,"topics":["lean4"],"latest_commit_sha":null,"homepage":"","language":"Lean","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/leanprover.png","metadata":{"files":{"readme":"README.md","changelog":null,"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-11-11T01:41:27.000Z","updated_at":"2025-02-03T08:36:24.000Z","dependencies_parsed_at":"2023-02-19T00:15:55.079Z","dependency_job_id":"73360f4e-17d8-4bc1-a5dd-c1486c3424f7","html_url":"https://github.com/leanprover/doc-gen4","commit_stats":null,"previous_names":[],"tags_count":14,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/leanprover%2Fdoc-gen4","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/leanprover%2Fdoc-gen4/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/leanprover%2Fdoc-gen4/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/leanprover%2Fdoc-gen4/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/leanprover","download_url":"https://codeload.github.com/leanprover/doc-gen4/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":239212561,"owners_count":19600830,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","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":["lean4"],"created_at":"2024-08-09T14:02:14.148Z","updated_at":"2025-10-31T15:30:41.020Z","avatar_url":"https://github.com/leanprover.png","language":"Lean","funding_links":[],"categories":["Lean","Core packages"],"sub_categories":[],"readme":"# `doc-gen4`\nDocument Generator for Lean 4\n\n## Usage\n`doc-gen4` is easiest to use via its custom Lake facet. The currently recommended setup for\nthis is that you create a nested project for documentation building inside of your lake project.\nTo do this:\n1. Create a subdirectory within your existing lake project called `docbuild`\n2. Create a `lakefile.toml` within `docbuild` with the following content:\n```toml\nname = \"docbuild\"\nreservoir = false\nversion = \"0.1.0\"\npackagesDir = \"../.lake/packages\"\n\n[[require]]\nname = \"Your Library Name\"\npath = \"../\"\n\n[[require]]\nscope = \"leanprover\"\nname = \"doc-gen4\"\n# If you are developing against a release candidate or a stable version `v4.x`, replace `main` below by `v4.x`.\n# If you do not use `main` keep in mind to update this field as you update your Lean version.\nrev = \"main\"\n```\n3. Run `lake update doc-gen4` within `docbuild` to pin `doc-gen4` and its dependencies to the chosen versions.\n   IMPORTANT: If you depend on [mathlib4](https://github.com/leanprover-community/mathlib4) run\n   `MATHLIB_NO_CACHE_ON_UPDATE=1 lake update doc-gen4` instead to mitigate a small issue in\n   mathlib's caching mechanism for now.\n4. If your parent project has dependencies you want to run `lake update YourLibraryName` within\n  `docbuild` whenever you update the dependencies of your parent project.\n\nAfter this setup step you can generate documentation for an entire library and all files imported\nby that library using the following command within `docbuild`:\n```\nlake build YourLibraryName:docs\n```\nIf you have multiple libraries you want to generate full documentation for:\n```\nlake build Test:docs YourLibraryName:docs\n```\n\nNote that `doc-gen4` currently always generates documentation for `Lean`, `Init`, `Lake` and `Std`\nin addition to the provided targets.\n\nThe root of the built docs will be `docbuild/.lake/build/doc/index.html`.\nHowever, due to the \"Same Origin Policy\", the generated website will be partially broken if you just\nopen the generated html files in your browser.  You need to serve them from a proper http server for\nit to work. An easy way to do that is to run `python3 -m http.server` from the `docbuild/.lake/build/doc`\ndirectory.\n\n## Requirements to run `doc-gen4`\nIn order to compile itself `doc-gen4` requires:\n- a Lean 4 or `elan` installation\n- a C compiler if on Linux or MacOS (on Windows it will use Lean's built-in clang compiler)\n\nApart from this the only requirement for `lake build YourLibraryName:docs` to work is that your\ntarget library builds, that is `lake build YourLibraryName` exits without an error. If this requirement\nis not fulfilled, the documentation generation will fail and you will end up with\npartial build artefacts in `docbuild/.lake/build/doc`. Note that `doc-gen4` is perfectly capable of\ngenerating documentation for Lean code that contains `sorry`, just not for code\nthat doesn't compile.\n\nIf you are working on a project that only partially compiles but can't fix the\nerrors from the top of your head, you can try to remove `import`s of both the failing files\nand all files that refer to the failing ones from your top level library file.\nLike this you will end up with an incomplete documentation but at least working\ndocumentation of your project.\n\nNote that we do not recommend this approach and suggest to instead make sure your\nprojects always compile by using CI to prevent broken code from being added and `sorry`-ing\nout things that you intend to complete later.\n\n## Source locations\n\nSource locations default to guessing the Github repo for the library, but different different schemas can be used by setting the `DOCGEN_SRC` environment variable.  For\nexample, one can use links that open the local source file in VSCode by running lake with:\n```\nDOCGEN_SRC=\"vscode\" lake ...\n```\n\nThe different options are:\n\n * `DOCGEN_SRC=\"github\"` infers the\n   Github project for each library and uses source links to the Github source view.\n   This is the default if `DOCGEN_SRC` is unset.\n * `DOCGEN_SRC=\"file\"` creates references to local file references.\n * `DOCGEN_SRC=\"vscode\"` creates [VSCode URLs](https://code.visualstudio.com/docs/editor/command-line#_opening-vs-code-with-urls) to local files.\n\n## How does `docs#Nat.add` from the Lean Zulip work?\nIf someone sends a message that contains `docs#Nat.add` on the Lean Zulip this will\nautomatically link to `Nat.add` from the `mathlib4` documentation. The way that this\nfeature is implemented is by linking to `/find` of generated documentation in the following way:\n\u003chttps://example.com/path/to/docs/find/?pattern=Nat.add#doc\u003e in the case of the `mathlib4`\ndocumentation this ends up being to: \u003chttps://leanprover-community.github.io/mathlib4_docs/find/?pattern=Nat.add#doc\u003e.\nIf you wish to provide a similar feature to `docs#Nat.add` from the Lean Zulip for your documentation,\nthis is the way to go.\n\n## Development of doc-gen4\nYou can build docs using a modified `doc-gen4` as follows:  Replace the `doc-gen4` require from\ndocbuild with:\n```\n[[require]]\nname = \"doc-gen4\"\npath = \"../../path/to/your/doc-gen4\"\n```\n\nNote that if you modify the `.js` or `.css` files in `doc-gen4`, they won't necessarily be copied over when\nyou rebuild the documentation.  You can manually copy the changes to the `docbuild/.lake/build/doc` directory to make\nsure the changes appear, or just do a full recompilation (`lake clean` and `lake build` inside the `doc-gen4`\ndirectory.)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fleanprover%2Fdoc-gen4","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fleanprover%2Fdoc-gen4","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fleanprover%2Fdoc-gen4/lists"}