{"id":13800939,"url":"https://github.com/weavejester/codox","last_synced_at":"2025-10-04T02:25:56.476Z","repository":{"id":41388376,"uuid":"2673869","full_name":"weavejester/codox","owner":"weavejester","description":"Clojure documentation tool","archived":false,"fork":false,"pushed_at":"2024-08-14T18:05:12.000Z","size":585,"stargazers_count":675,"open_issues_count":47,"forks_count":97,"subscribers_count":7,"default_branch":"master","last_synced_at":"2025-09-13T04:56:57.182Z","etag":null,"topics":["clojure","docs-generator","documentation"],"latest_commit_sha":null,"homepage":"","language":"Clojure","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"epl-1.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/weavejester.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE.txt","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":"2011-10-30T04:43:00.000Z","updated_at":"2025-08-07T07:08:14.000Z","dependencies_parsed_at":"2024-01-05T21:51:52.766Z","dependency_job_id":"82e71380-e5bf-4dd5-91d7-633ca909ea56","html_url":"https://github.com/weavejester/codox","commit_stats":{"total_commits":431,"total_committers":33,"mean_commits":13.06060606060606,"dds":"0.12761020881670537","last_synced_commit":"6e2a89da8d72348e9d6723a502669f15e4fabc62"},"previous_names":[],"tags_count":64,"template":false,"template_full_name":null,"purl":"pkg:github/weavejester/codox","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/weavejester%2Fcodox","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/weavejester%2Fcodox/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/weavejester%2Fcodox/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/weavejester%2Fcodox/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/weavejester","download_url":"https://codeload.github.com/weavejester/codox/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/weavejester%2Fcodox/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":278254666,"owners_count":25956644,"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","status":"online","status_checked_at":"2025-10-04T02:00:05.491Z","response_time":63,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"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":["clojure","docs-generator","documentation"],"created_at":"2024-08-04T00:01:17.814Z","updated_at":"2025-10-04T02:25:56.452Z","avatar_url":"https://github.com/weavejester.png","language":"Clojure","funding_links":[],"categories":["Documentation","Clojure","Awesome ClojureScript"],"sub_categories":["Documentation"],"readme":"# Codox\n\nA tool for generating API documentation from Clojure or ClojureScript\nsource code.\n\n\n## Usage\n\n### Leiningen\n\nInclude the following plugin in your `project.clj` file or your global\nprofile:\n\n```clojure\n:plugins [[lein-codox \"0.10.8\"]]\n```\n\nThen run:\n\n```\nlein codox\n```\n\nThis will generate API documentation in the \"target/doc\" subdirectory\n(or wherever your project `:target-path` is set to).\n\n### Boot\n\nAdd boot-codox to your build.boot dependencies and require the namespace:\n```\n(set-env! :dependencies '[[boot-codox \"0.10.8\" :scope \"test\"]])\n(require '[codox.boot :refer [codox]])\n```\n\nYou can see the options available on the command line:\n\n```\n$ boot codox -h\n```\n\nor in the REPL:\n\n```\nboot.user=\u003e (doc codox)\n```\n\nRemember to output files to the target directory with boot's built-in `target` task:\n\n```\n$ boot codox target\n```\n\n### deps.edn\n\nAdd an alias to your `deps.edn`:\n\n```clojure\n:codox {:extra-deps {codox/codox {:mvn/version \"0.10.8\"}}\n        :exec-fn codox.main/generate-docs\n        :exec-args {:source-paths [\"path/to/src\"]}}\n```\n\nWhen using `deps.edn`, project options should be added to the\n`:exec-args` map in your Codox alias, as above.  This behavior differs\nfrom the examples in \"Project Options\" section, which use the\nLeiningen configuration format.\n\nRun Codox via `-X` like this:\n\n```shell\nclojure -X:codox\n```\n\nNote: Codox expects the code it analyzes to be on the classpath so you\nmay need to specify additional aliases from your project to make that\nhappen, e.g., `clojure -X:dev:codox`.\n\n## Breaking Changes in 0.9\n\nIn preparation for a 1.0 release, Codox 0.9 has a number of breaking\nchanges:\n\n* The Leiningen plugin has been changed from `codox` to `lein-codox`\n* The Leiningen task has been changed from `lein doc` to `lein codox`\n* The default output path has been changed from `doc` to `target/doc`\n* The `:sources` option has been renamed to `:source-paths`\n* The `:output-dir` option has been renamed to `:output-path`\n* The `:defaults` option has been renamed to `:metadata`\n* The `:include` and `:exclude` options have been replaced with `:namespaces`\n* All the `:src-*` options have been replaced with `:source-uri`\n\nSee the \"Source Files\" section for information on the `:namespaces`\noption, and the \"Source Links\" section for information on the\n`:source-uri` option.\n\n\n## Examples\n\nSome examples of API docs generated by Codox in real projects:\n\n* [Medley](https://weavejester.github.io/medley/medley.core.html)\n* [Compojure](https://weavejester.github.io/compojure/)\n* [Hiccup](https://weavejester.github.io/hiccup/)\n* [Ring](https://ring-clojure.github.io/ring/)\n\n\n## AOT Compilation\n\nAOT-compiled namespaces will lose their metadata, which mean you'll\nlose documentation for namespaces. Avoid having global `:aot`\ndirectives in your project; instead, place them in a specialized\nprofile, such as `:uberjar`.\n\n\n## Project Options\n\nCodox can generate documentation from Clojure or ClojureScript. By\ndefault it looks for Clojure source files, but you can change this to\nClojureScript by setting the `:language` key:\n\n```clojure\n:codox {:language :clojurescript}\n```\n\n### Source Files\n\nBy default Codox looks for source files in the `:source-paths` of your\nproject, but you can change this just for Codox by placing the\nfollowing in your `project.clj` file:\n\n```clojure\n:codox {:source-paths [\"path/to/source\"]}\n```\n\nThe `:namespaces` option can be used to restrict the documentation to\na specific set of namespaces:\n\n```clojure\n:codox {:namespaces [library.core library.io]}\n```\n\nRegular expressions can also be used for more general matching:\n\n```clojure\n:codox {:namespaces [#\"^library\\.\"]}\n```\n\nFor excluding only internal namespaces, it's sometimes useful to use\nnegative lookahead:\n\n```clojure\n:codox {:namespaces [#\"^library\\.(?!internal)\"]}\n```\n\nTo override the namespaces list and include all namespaces, use `:all`\n(the default):\n\n```clojure\n:codox {:namespaces :all}\n```\n\nThe `:exclude-vars` option can be used to exclude vars that match a\nregular expression. Set to `nil` to disable. By default vars generated\nby record constructor functions are excluded (such as `-\u003eFoo` and\n`map-\u003eFoo`):\n\n```clojure\n:codox {:exclude-vars #\"^(map)?-\u003e\\p{Upper}\"}\n```\n\nCodox constructs documentation from metadata on vars and namespaces.\nYou can specify a set of default metadata using the `:metadata` map:\n\n```clojure\n:codox {:metadata {:doc \"FIXME: write docs\"}}\n```\n\n### Documentation Files\n\nAs well as source files, Codox also tries to include documentation\nfiles as well. By default it looks for these in the `doc` directory,\nbut you can change this with:\n\n```clojure\n:codox {:doc-paths [\"path/to/docs\"]}\n```\n\nDocumentation files will appear in the output sorted by their\nfilename. If you want a particular order, one solution is to prefix\nyour files with `01`, `02`, etc. Alternatively, you can also define\nthe documentation files explicitly:\n\n```clojure\n:codox {:doc-files [\"doc/intro.md\", \"doc/tutorial.md\"]}\n```\n\nIf `:doc-files` is specified, then `:doc-paths` is ignored. Currently\nonly markdown files (`.md` or `.markdown`) are supported. Any links\nbetween markdown files will be converted to their HTML equivalents\nautomatically.\n\n\n### Output Files\n\nTo write output to a directory other than the default, use the\n`:output-path` key:\n\n```clojure\n:codox {:output-path \"codox\"}\n```\n\nTo use a different output writer, specify the fully qualified symbol of the\nwriter function in the `:writer` key:\n\n```clojure\n:codox {:writer codox.writer.html/write-docs}\n```\n\nBy default the writer will include the project name, version and\ndescription in the output. You can override these by specifying a\n`:project` map in your Codox configuration:\n\n```clojure\n:codox {:project {:name \"Example\", :version \"1.0\", :description \"N/A\"}}\n```\n\nNote: when using `deps.edn`, these entries should be added to the top\nlevel of the Codox configuration map (i.e. not under `:project`).\n\n### Source Links\n\nIf you have the source available at a URI and would like to have links\nto the function's source file in the documentation, you can set the\n`:source-uri` key:\n\n```clojure\n:codox {:source-uri \"https://github.com/foo/bar/blob/{version}/{filepath}#L{line}\"}\n```\n\nThe URI is a template that may contain the following keys:\n\n* `{filepath}`   - the file path from the root of the repository\n* `{basename}`   - the basename of the file\n* `{classpath}`  - the relative path of the file within the source directory\n* `{line}`       - the line number of the source file\n* `{version}`    - the version of the project\n* `{git-commit}` - the Git commit id of the repository\n\nYou can also assign different URI templates to different paths of your\nsource tree. This is particularly useful for created source links from\ngenerated source code, such as is the case with [cljx][].\n\nFor example, perhaps your Clojure source files are generated in\n`target/classes`. To link back to the original .cljx file, you could do:\n\n```clojure\n:codox\n{:source-uri\n {#\"target/classes\" \"https://github.com/foo/bar/blob/master/src/{classpath}x#L{line}\"\n  #\".*\"             \"https://github.com/foo/bar/blob/master/{filepath}#L{line}\"}}\n```\n\n[cljx]: https://github.com/lynaghk/cljx\n\n### HTML Transformations\n\nThe HTML writer can be customized using [Enlive][]-style\ntransformations. You can use these to modify the HTML documents\nproduced in arbitrary ways, but the most common use is to add in new\nstylesheets or scripts.\n\nThe transforms live in the `:transforms` key, in the `:html` map, and\nconsist of a vector that matches selectors to transformations, in the\nsame way that `let` matches symbols to values.\n\nFor example, the following code adds a new `\u003cscript\u003e` element as the\nlast child of the `\u003chead\u003e` element:\n\n```clojure\n:html {:transforms [[:head] [:append [:script \"console.log('foo');\"]]]}\n```\n\nThe selectors follow the [Enlive selector syntax][].\n\nThe transformations are a little different. There are five transforms,\n`:append`, `:prepend`, `:after`, `:before` and `:substitute`. These\nmatch to the corresponding [Enlive transformations][], but expect\n[Hiccup][]-style arguments.\n\n[enlive]: https://github.com/cgrand/enlive\n[enlive selector syntax]: https://github.com/cgrand/enlive#selector-syntax\n[enlive transformations]: https://github.com/cgrand/enlive#transformations\n[hiccup]: https://github.com/weavejester/hiccup\n\n### HTML Output Options\n\nThe HTML writer also has one other customization option.\n\nBy default the namespace list is nested, unless there is only one\nnamespace in the library. To override this, set the `:namespace-list`\noption in the `:html` map to either `:nested` or `:flat`.\n\n```clojure\n:html {:namespace-list :flat}\n```\n\n### Themes\n\nThemes are HTML transformations packaged with resources. Because\nthey're data-driven and based on transformation of the generated\ndocumentation, multiple themes can be applied. The default theme is\n`:default`. Themes can be added by changing the `:themes` key:\n\n```clojure\n:themes [:my-custom-theme]\n```\n\nTo create a theme, you'll need to place the following resource in the\nclasspath, either directly in your project, or via a dependency:\n\n    codox/theme/my-custom-theme/theme.edn\n\nThis edn file should contain a map of two keys: `:transforms` and\n`:resources`.\n\nThe `:transforms` key contains an ordered collection of HTML\ntransformations. See the previous section for more information on the\nsyntax.\n\nThe `:resources` key contains a list of sub-resources that will be\ncopied to the target directory when the documentation is compiled. For\nexample, if you define a sub-resource `css/main.css`, then Codox will\ncopy the resource `codox/theme/foo/css/main.css` to the file\n`css/main.css` in the target directory.\n\nThemes can also take parameters. You can put in a keyword as a\nplaceholder, and then end users can specify the value that should\nreplace the keyword. This is achieved by using a vector instead of a\nkeyword to specify the theme:\n\n```clojure\n:themes [[keyword {placeholder value}]]\n```\n\nFor example:\n\n```clojure\n:themes [[:my-custom-theme {:some-value \"foobar\"}]]\n```\n\nCodox will look for the keyword `:some-value` in the theme file, and\nreplace it with the string `\"foobar\"`.\n\nIf you want to take a look at a complete theme, try the\n[default theme][] for Codox.\n\n[default theme]: https://github.com/weavejester/codox/tree/master/codox/resources/codox/theme/default\n\n\n## Metadata Options\n\nTo force Codox to skip a public var, add `:no-doc true`\nto the var's metadata. For example:\n\n```clojure\n;; Documented\n(defn square\n  \"Squares the supplied number.\"\n  [x]\n  (* x x))\n\n;; Not documented\n(defn ^:no-doc hidden-square\n  \"Squares the supplied number.\"\n  [x]\n  (* x x))\n```\n\nYou can also skip namespaces by adding `:no-doc true` to the\nnamespace's metadata. *This currently only works for Clojure code, not\nClojureScript.* For example:\n\n```clojure\n(ns ^:no-doc hidden-ns)\n```\n\nTo denote the library version the var was added in, use the `:added`\nmetadata key:\n\n```clojure\n(defn square\n  \"Squares the supplied number.\"\n  {:added \"1.0\"}\n  [x]\n  (* x x))\n```\n\nSimilar, deprecated vars can be denoted with the `:deprecated`\nmetadata key:\n\n```clojure\n(defn square\n  \"Squares the supplied number.\"\n  {:deprecated \"2.0\"}\n  [x]\n  (* x x))\n```\n\n\n## Docstring Formats\n\nBy default, docstrings are rendered by Codox as fixed-width plain\ntext, as they would be on a terminal. However, you can override this\nbehavior by specifying an explicit format for your docstrings.\n\nCurrently there are only two formats for docstrings: plaintext and\nmarkdown. The markdown format includes extensions for code blocks,\ntables, and, like the plaintext format, URLs are automatically encoded\nas links.\n\nYou can specify docstring formats via a var's metadata, using the\n`:doc/format` option:\n\n```clojure\n(defn foo\n  \"A **markdown** formatted docstring.\"\n  {:doc/format :markdown}\n  [x])\n```\n\nOr you can specify the docstring format globally by adding it to the\n`:metadata` map in your project.clj file:\n\n```clojure\n:codox {:metadata {:doc/format :markdown}}\n```\n\nMarkdown docstrings also support wikilink-style relative links, for\nreferencing other vars. Vars in the current namespace will be matched\nfirst, and then Codox will try and find a best match out of all the\nvars its documenting.\n\n```clojure\n(defn bar\n  \"See [[foo]] and [[user/square]] for other examples.\"\n  {:doc/format :markdown}\n  [x])\n```\n\n\n## Live Documentation\n\nYou can make the code in your documentation live and interactive by\nusing the [Klipse theme][] written by [Yehonathan Sharvit][]. This\nthird-party theme integrates the generated docs with the [Klipse][]\ncode evaluator.\n\n[klipse theme]: https://github.com/viebel/codox-klipse-theme\n[yehonathan sharvit]: https://github.com/viebel\n[klipse]: https://github.com/viebel/klipse\n\n\n## License\n\nCopyright © 2018 James Reeves\n\nDistributed under the Eclipse Public License either version 1.0 or (at\nyour option) any later version.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fweavejester%2Fcodox","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fweavejester%2Fcodox","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fweavejester%2Fcodox/lists"}