docs: update install, contrib, and usage documentation#1222
Merged
Conversation
1f86323 to
5abecac
Compare
3141185 to
7fa5cf0
Compare
992195a to
12e8954
Compare
|
This bot triages pull requests in order to help the maintainers
This bot will not automatically close stale pull requests. To remove the stale status, you can:
To avoid automatic lifecycle management of this pull request, add |
Contributor
Author
|
note: there are a lot of pushes to this tree because i don't currently have a way to preview GFM locally (and need to ensure that things like references and formatting lines up with what i'm expecting); by pushing even small changes, i get a fast feedback loop on what the actual rendered HTML will be. because of this, i have disabled the pipelines from running to avoid wasting compute unecessarily. they will be re-enabled once this PR is no longer a draft. |
This change refactors documentation, especially //:README.md, //:CONTRIBUTING.md, and centralized most of the rest of the contributing and usage documentation into `//doc`. There are some additional minor changes to the development shell and pipeline configuration. Documentation changes focus on cleaning up erroneous language, reformatting, and restructuring docs in order to reduce visual noise - the goals are to enable users and contributors to find what they're looking for much more quickly, reduce (sometimes erroneous) duplication, and present a structured approach for where to put docs. Additionally: - Added CI pipeline badge for the `trunk` workflow in `//:README.md` - Converted embedded emoji characters to GitHub's emoji syntax - Simplified `//:README.md` by moving inline documentation out to files under `//doc`. - Removed most inline CLI "documentation" (lists of commands) with a link to the generated CLI documentation. - Moved most sections with image and installation instructions into `<details>` elements - Replaced references to gitter with matrix - Added `treefmt-nix` to the flake, and formatted all non-generated documentation was with `nix fmt` (running `mdformat` under the hood) - Regenerated //doc/md and //doc/man and refactored inline docs from various pages that were iterating out command line details so that they simply point to //doc/md instead - Rewrote contributing docs to focus on using `nix`, to ensure that the development shell is used. This enforces consistency across different platforms with the revision and configuration of each tool we use, and simplifies the onboarding story for contributors -- they only need to install and configure nix (and optionally direnv). A dev container will be provided in the future [0] as an alternative for users on Windows (who can use WSL) or want to avoid installing `nix`. - Added `pinact` to the flake to support pinning action libraries used in workflows. - Added flake checks for codespell and pinact. Combined with treefmt, this entirely replaces //.github/workflows:lint.yml. With this change, codespell's execution was fixed to properly execute on all files, and the configuration file was refactored to properly ignore package-lock.json files. - Added a workflow job to run flake checks. [0]: #1364 Closes: #1212 #1276 #1330 #1357 Change-Id: I6f4b5f5ca73780cecf66a553cce80aa3f75df2ce
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
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
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.
This change refactors documentation, especially //:README.md,
//:CONTRIBUTING.md, and centralized most of the rest of the contributing
and usage documentation into
//doc. There are some additional minorchanges to the development shell and pipeline configuration.
Documentation changes focus on cleaning up erroneous language,
reformatting, and restructuring docs in order to reduce visual noise -
the goals are to enable users and contributors to find what they're looking
for much more quickly, reduce (sometimes erroneous) duplication, and
present a structured approach for where to put docs.
Additionally:
trunkworkflow in//:README.md//:README.mdby moving inline documentation out to filesunder
//doc.link to the generated CLI documentation.
<details>elementstreefmt-nixto the flake, and formatted all non-generateddocumentation was with
nix fmt(runningmdformatunder the hood)pages that were iterating out command line details so that they simply
point to //doc/md instead
nix, to ensure that thedevelopment shell is used. This enforces consistency across different
platforms with the revision and configuration of each tool we use, and
simplifies the onboarding story for contributors -- they only need to
install and configure nix (and optionally direnv). A dev container
will be provided in the future 0 as an alternative for users on
Windows (who can use WSL) or want to avoid installing
nix.pinactto the flake to support pinning action libraries usedin workflows.
this entirely replaces //.github/workflows:lint.yml. With this change,
codespell's execution was fixed to properly execute on all files, and
the configuration file was refactored to properly ignore
package-lock.json files.
Closes: #1212 #1276 #1330 #1357
Change-Id: I6f4b5f5ca73780cecf66a553cce80aa3f75df2ce