{"id":23086471,"url":"https://github.com/cliabhach/publish_docs","last_synced_at":"2026-05-15T12:32:35.245Z","repository":{"id":87612856,"uuid":"488474653","full_name":"Cliabhach/publish_docs","owner":"Cliabhach","description":"Dart library for building and publishing documentation","archived":false,"fork":false,"pushed_at":"2023-01-23T10:29:25.000Z","size":2239,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":2,"default_branch":"main","last_synced_at":"2025-07-24T16:25:36.530Z","etag":null,"topics":["dart","documentation"],"latest_commit_sha":null,"homepage":"","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Cliabhach.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":"2022-05-04T06:21:10.000Z","updated_at":"2022-05-29T20:31:25.000Z","dependencies_parsed_at":null,"dependency_job_id":"5ae7e4fb-a54d-43c5-8343-46144754c46d","html_url":"https://github.com/Cliabhach/publish_docs","commit_stats":null,"previous_names":[],"tags_count":31,"template":false,"template_full_name":null,"purl":"pkg:github/Cliabhach/publish_docs","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Cliabhach%2Fpublish_docs","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Cliabhach%2Fpublish_docs/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Cliabhach%2Fpublish_docs/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Cliabhach%2Fpublish_docs/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Cliabhach","download_url":"https://codeload.github.com/Cliabhach/publish_docs/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Cliabhach%2Fpublish_docs/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33067221,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-15T11:35:32.926Z","status":"ssl_error","status_checked_at":"2026-05-15T11:35:31.362Z","response_time":103,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: 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":["dart","documentation"],"created_at":"2024-12-16T18:54:26.131Z","updated_at":"2026-05-15T12:32:35.228Z","avatar_url":"https://github.com/Cliabhach.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# publish_docs (not yet on pub.dev)\n\n[![style: very good analysis][very_good_analysis_badge]][very_good_analysis_link]\n[![License: BSD-3-Clause][license_badge]][license_link]\n\nPublish your documentation to GitHub Pages!\n\n_This package is in a pre-release form and not yet ready for general\nuse. Feel free to try it out, but understand that the public usage and\nintegration steps may change significantly before the first public\nrelease._\n\n## Concept\n\nStrictly speaking, this does everything _but_ the actual publish step\nfor you. That last step is easy to perform, though - it's nothing more\nthan `git push`.\n\nWe make the following assumptions about your project and what output\nyou would like:\n\n1. The project uses [`git` version control](https://git-scm.com/)\n2. The project doesn't share its git repository with other projects\n3. All the generated docs should use the same theming\n4. You already have a `gh-pages` branch\n5. Your GitHub Pages settings are configured in a certain way\n\n## Dependencies\n\nThe only direct runtime dependencies are `dartdoc` and `git`.\n\n### git\n\n#### Why use `git`?\n\nWe use this library to execute `git` commands, which let us query and\nmanipulate the project's git repository. The library also offers handy\ndata models for `Commit`s and `BranchReference`s, among other\nabstractions. It is not an exaggeration to say that our project here\ncould not exist if the `git` library was not already published.\n\nWhile we do have _access_ to do other things, our code actively tries\nto avoid damaging your git repository or deleting any important files.\nAn established library like this one makes it easier for us to avoid\nthe really dangerous things.\n\n#### How do we use `git`?\n\nWe use the `git format-patch` command to create each documentation\nupdate. This patch is then applied to the GitHub Pages branch.\n\n[Adding docs changes to the repo](#adding-docs-changes-to-the-repo)\nhas more details on why we do this, and\n[gh_pages_patch.dart][pages_patch_file] contains a good bit of the\nrelevant code.\n\nHere is a rundown of the other kinds of commands we run, with\nexplanations of why they're in this project:\n\n| Command       | Our usage                                        |\n|---------------|--------------------------------------------------|\n| git add       | Add newly-generated docs to the git index        |\n| git am        | Apply the output of format-patch to gh-pages     |\n| git checkout  | 1: Load prior docs, 2: Switch to gh-pages branch |\n| git commit    | Create one of two temp commits for format-patch  |\n| git rev-parse | Read in the short hash for a specific commit     |\n| git reset     | Remove the two temp commits for format-patch     |\n| git stash     | Save locally-changed files so we don't edit them |\n\nIn addition to the above, we do use some functions exposed by the\nlibrary itself. For example, `GitDir.commits` internally invokes\n`git rev-list`. Please refer to the source code itself (and the\n[GitCommands class][git_commands_class] in particular) for a better\nunderstanding of what `git` library functions we call.\n\n#### Can I change the `git` dependency?\n\nAs long as this library has null-safety and lets us run `git` commands,\nit doesn't matter too much which version is in use. There should be no\nproblem upgrading to newer versions of this library.\n\n### dartdoc\n\n#### Why use `dartdoc`?\n\nWe use this library to generate documentation for dart code. While\nthere are some limitations (see [Limitations](#limitations)),\n`dartdoc` is remarkably good at creating readable documentation. It\nhandles all the cross-references and annotation information, since it\nbuilds a full package graph of all the code and comments in your\nproject. This makes `dartdoc` a very powerful basis for _any_ kind of\nvisual representation of your project, not just documentation.\n\nIt's easy to imagine `dartdoc` supporting even more features in the\nfuture, such as graphs [in the style of doxygen][doxygen_diagrams].\n\n#### How do we use `dartdoc`?\n\nWe integrate into the `dartdoc` library through two main avenues:\n\n1. The public API. This is [still experimental][dartdoc_library], as\nof Dartdoc 5.0.1, and may change in future versions.\n2. Your project's `dartdoc_options.yaml` file. This is stable - you\nmight even have one of these defined in your repository.\n3. Custom runtime resources. This is _very_ new, and the main reason\nwhy we require such a recent version of the `dartdoc` library.\n\nFor the most part, you can think of the `:generate` command as a\ndrop-in replacement for `dart doc`. With no additional configuration,\nyou'll get the same documentation output you've come to expect, along\nwith our replacement for the default `dartdoc` assets.\n\nWhen you run `updateGitHubDocs` or `updateGitHubPages`, the situation\nis a little different. Here, we do a number of git operations both\nbefore and after the calls into `dartdoc`, and we make great use of\nthe code analysis/metadata offered by [PubMeta][dartdoc_pub_meta].\n\n#### Can I change the `dartdoc` dependency?\n\nYes, but with a caveat - make sure that you choose a version that is\nrecent enough to include the dart-based navigation code. Before\n[the frontend JS was fully converted to Dart][dartdoc_js_commit], the\nfiles that could be copied with the `resourcesDir`/`resources-dir`\noption had different names.\n\n## Usage\n\n### Preparation\n\nYour project must work with `dartdoc` before using `publish_docs`.\n\n1. Run `dart analyze`. Fix all errors (warnings _should_ be fixed, but\nthe library will still be able to create docs if there are warnings).\n2. Make a `dartdoc_options.yaml` if you don't have one already.\n3. Run `dart doc` to use the version of `dartdoc` that's bundled with\nDart's SDK.\n\nIf `dart doc` finishes successfully, without any errors, then you're\nready to integrate `publish_docs` into your project. As a special\ncase: if there is a version conflict or a version-specific bug in the\n`dart doc` output (such as [Issue 2934][dartdoc_2934]), then you may\nwant to skip ahead to the next step anyway.\n\n### Integration\n\nAdd `publish_docs` to your project's pubspec.yaml as a\n[dev-dependency][dart_dev_dependency]. Run the appropriate `pub get`\ncommand for your project (probably `dart pub get` or\n`flutter pub get`) to update your project's pubspec.lock.\n\n...That's basically it. You can now use a `pub run` command to try out\nthe tool. We recommend starting off with the `publish_docs` command:\n\n```shell\n# For Dart projects\ndart pub run publish_docs\n# For Flutter projects\nflutter pub run publish_docs\n```\n\n### Customisation\n\n#### Basics\n\nBy default, we make use of the following 4 directories:\n\n`doc/api/` - the default output directory for `:generate`.\n\n`doc/assets/` - the default directory for runtime resources.\n\n`docs/api/` - the default output directory for `:commit`.\n\nYou can change the appearance and behavior of the generated docs by\nadding any of the currently-supported files to `doc/assets/`. We will\nautomatically use our [bundled resources](lib/resources/dartdoc-5.1.0)\nto add any important files that you didn't provide there.\n\n#### Supported files\n\n_As seen in [the generated list][dartdoc_asset_list]._\n\n- `docs.dart.js`\n- `docs.dart.js.map`\n- `favicon.png`\n- `github.css`\n- `highlight.pack.js`\n- `play_button.svg`\n- `readme.md`\n- `styles.css`\n\nNote that this list is subject to change in future releases of the\n`dartdoc` library. Until the `dartdoc` library API stabilises, you\nshould pay careful attention the exact version of `publish_docs` you\nuse.\n\n## Limitations\n\n### Adding docs changes to the repo\n\nSince documentation tends to take up an awful lot of space, we try to\nreuse existing files where possible. To that end we generate new docs\nright on top of existing documentation, and create a patch out of the\ndiff between the old and new.\n\nWe make three assumptions about the process:\n\n1. Generated documentation is stored on its own branch.\n2. Each commit on that branch has just one version of the docs.\n3. That branch already exists and has at least one commit.\n\nThis matches a classic 'gh-pages' approach to GitHub Pages, but you\ndon't _have_ to follow that. The settings part of your GitHub repo\nlets you choose to load documentation from any branch, not just one\ncalled 'gh-pages', and of course the one-version-per-commit thing is\njust a convention.\n\nKeeping those three assumptions, though, does make it a lot easier for\nthis project to work properly. In a future version of `publish_docs`,\nperhaps we'll support more kinds of repo configuration. The wiki for a\nGitHub project is only a special kind of Git Repository, after all, so\nthere might even be an option to upload markdown-style docs into that.\n\n### Our stance on command-line `dartdoc` options\n\nThere are things that `dartdoc` can do that are only configured with\ncommand-line flags. Other options can only be configured through a\n`dartdoc_options.yaml` file. And then there are options that can be\ndefined in either way.\n\nRoughly speaking, command-line-only options have the greatest impact.\nThey tend to change the output in significant ways, from the obvious\n`--help` and `--format`, to the more subtle `--inject-html` and\n`--validate-links`.\n\nFor this reason, we make an effort to avoid using command-line-only\nflags where alternatives exist. The main exception is the\n`--resources-dir` option, which cannot be configured in any other way.\nWe provide a value of `doc/assets/` for that.\n\n\n[license_badge]: https://img.shields.io/badge/license-BSD_3_Clause-blue.svg\n[license_link]: https://opensource.org/licenses/BSD-3-Clause\n[very_good_analysis_badge]: https://img.shields.io/badge/style-very_good_analysis-B22C89.svg\n[very_good_analysis_link]: https://pub.dev/packages/very_good_analysis\n[dart_dev_dependency]: https://dart.dev/tools/pub/dependencies#dev-dependencies\n[dartdoc_js_commit]: https://github.com/dart-lang/dartdoc/commit/a33ec963eb5b9aa91\n[dartdoc_library]: https://pub.dev/documentation/dartdoc/5.0.1/dartdoc/dartdoc-library.html\n[dartdoc_pub_meta]: https://pub.dev/documentation/dartdoc/5.0.1/dartdoc/PackageMeta-class.html\n[dartdoc_2934]: https://github.com/dart-lang/dartdoc/issues/2934\n[dartdoc_asset_list]: https://github.com/dart-lang/dartdoc/blob/26d38618/lib/src/generator/html_resources.g.dart\n[doxygen_diagrams]: https://www.doxygen.nl/manual/diagrams.html\n[git_commands_class]: lib/src/git/commands.dart\n[pages_patch_file]: lib/src/operation/gh_pages_patch.dart\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcliabhach%2Fpublish_docs","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcliabhach%2Fpublish_docs","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcliabhach%2Fpublish_docs/lists"}