From fb54e91183efedbb054522c209257cef59b73cd2 Mon Sep 17 00:00:00 2001 From: "Joshua A. Anderson" Date: Fri, 10 May 2024 10:16:43 -0400 Subject: [PATCH] Add documentation footer. Also apply typos in pre-commit and clean up many MD links. --- .pre-commit-config.yaml | 4 ++ DESIGN.md | 5 -- README.md | 5 +- doc/src/SUMMARY.md | 2 +- doc/src/developers/contributing.md | 90 ++++++++++++++++++++++++++++++ doc/src/developers/style.md | 31 ++++++++-- doc/src/developers/testing.md | 10 ++-- doc/src/guide/python/actions.md | 17 +++--- doc/src/guide/tutorial/index.md | 5 +- doc/src/guide/tutorial/submit.md | 5 +- doc/theme/index.hbs | 2 +- validate/validate.py | 4 +- 12 files changed, 150 insertions(+), 30 deletions(-) create mode 100644 doc/src/developers/contributing.md diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml index ce8d172..fdcd5dd 100644 --- a/.pre-commit-config.yaml +++ b/.pre-commit-config.yaml @@ -44,3 +44,7 @@ repos: - --license-file=LICENSE - --add=Part of row, released under the BSD 3-Clause License. - --comment-prefix=// +- repo: https://github.com/crate-ci/typos + rev: v1.21.0 + hooks: + - id: typos diff --git a/DESIGN.md b/DESIGN.md index 75c9b24..79d67de 100644 --- a/DESIGN.md +++ b/DESIGN.md @@ -52,11 +52,6 @@ Row is yet another workflow engine that automates the process of executing **act Ideas: * List scheduler jobs and show useful information. * Cancel scheduler jobs specific to actions and/or directories. -* Command to uncomplete an action for a set of directories. This would remove the product files and - update the cache. -* Some method to clear any cache (maybe this instead of uncomplete?). This would allow - users to discover changed action names, changed products, manually uncompleted - actions, and deal with corrupt cache files. ## Overview diff --git a/README.md b/README.md index 73f1ab9..4ab0609 100644 --- a/README.md +++ b/README.md @@ -62,5 +62,6 @@ dir6 completed 0.3 ## History -**Row** is a spiritual successor to -[signac-flow](https://docs.signac.io/projects/flow/en/latest/). +**Row** is a spiritual successor to [signac-flow][flow]. + +[flow]: https://docs.signac.io/projects/flow/en/latest/. diff --git a/doc/src/SUMMARY.md b/doc/src/SUMMARY.md index aa05657..8b70b30 100644 --- a/doc/src/SUMMARY.md +++ b/doc/src/SUMMARY.md @@ -55,7 +55,7 @@ - [Release notes]() - [Migrating from signac-flow](signac-flow.md) - [For developers](developers/index.md) - - [Contributing]() + - [Contributing](developers/contributing.md) - [Code style](developers/style.md) - [Testing](developers/testing.md) - [Documentation](developers/documentation.md) diff --git a/doc/src/developers/contributing.md b/doc/src/developers/contributing.md new file mode 100644 index 0000000..fe8cf03 --- /dev/null +++ b/doc/src/developers/contributing.md @@ -0,0 +1,90 @@ +# Contributing + +Contributions are welcomed via [pull requests on GitHub][github]. Contact the **row** +developers before starting work to ensure it meshes well with the planned development +direction and standards set for the project. + +[github]: https://github.com/glotzerlab/gsd/row + +## Features + +### Implement functionality in a general and flexible fashion + +New features should be applicable to a variety of use-cases. The **row** developers can +assist you in designing flexible interfaces. + +### Maintain performance of existing code paths + +Expensive code paths should only execute when requested. + +## Version control + +### Base your work off the correct branch + +- Base all new work on `trunk`. + +### Propose a minimal set of related changes + +All changes in a pull request should be closely related. Multiple change sets that are +loosely coupled should be proposed in separate pull requests. + +### Agree to the Contributor Agreement + +All contributors must agree to the Contributor Agreement before their pull request can +be merged. + +### Set your git identity + +Git identifies every commit you make with your name and e-mail. [Set your identity][id] +to correctly identify your work and set it identically on all systems and accounts where +you make commits. + +[id]: http://www.git-scm.com/book/en/v2/Getting-Started-First-Time-Git-Setup + +## Source code + +### Use a consistent style + +The **Code style** section of the documentation sets the style guidelines for **row** +code. + +### Document code with comments + +Use **Rust** documentation comments for classes, functions, etc. Also comment complex +sections of code so that other developers can understand them. + +### Compile without warnings + +Your changes should compile without warnings. + +## Tests + +### Write unit tests + +Add unit tests for all new functionality. + +### Validity tests + +The developer should run research-scale simulations using the new functionality and +ensure that it behaves as intended. When appropriate, add a new test to `validate.py`. + +## User documentation + +### Write user documentation + +Document all new configuration keys, command line options, command line tools, +and any important user-facing change in the mdBook documentation. + +### Tutorial + +When applicable, update or write a new tutorial. + + +### Add developer to the credits + +Update the contributors documentation to name each developer that has contributed to the +code. + +### Propose a change log entry + +Propose a short concise entry describing the change in the pull request description. diff --git a/doc/src/developers/style.md b/doc/src/developers/style.md index b0bb84a..6718f61 100644 --- a/doc/src/developers/style.md +++ b/doc/src/developers/style.md @@ -1,7 +1,30 @@ # Code style -**Row** code follows the -[Rust style guide](https://doc.rust-lang.org/style-guide/index.html). +## Rust -**Row's** [pre-commit](https://pre-commit.com/) configuration applies style fixes -with `rustfmt` checks for common errors with `clippy`. +**Row's** rust code follows the [Rust style guide][1]. **Row's** [pre-commit][2] +configuration applies style fixes with `rustfmt` checks for common errors with `clippy`. + +[1]: https://doc.rust-lang.org/style-guide/index.html +[2]: https://pre-commit.com/ + +## Python + +**Row's** pre-commit configuration both formats and checks Python code with `ruff`. + +## Markdown + +Wrap **Markdown** files at 88 characters wide, except when not possible (e.g. when +formatting a table). Follow layout and design patterns established in existing markdown +files. + +## Spelling/grammar + +Contributors **must** configure their editors to perform spell checking (and preferably +grammar checking as well). **Row's** pre-commit runs +[typos](https://github.com/crate-ci/typos) which has a low rate of false positives. +Developers *should* also configure a more thorough checker of their choice to ensure +that code comments and documentation are free of errors. Suggested tools: +* [typos](https://github.com/crate-ci/typos) +* [ltex-ls](https://github.com/valentjn/ltex-ls) +* [cspell](https://cspell.org/) diff --git a/doc/src/developers/testing.md b/doc/src/developers/testing.md index eca87af..4f67fa6 100644 --- a/doc/src/developers/testing.md +++ b/doc/src/developers/testing.md @@ -14,8 +14,9 @@ with any test that is automatically run concurrently. Check for this with: ```bash rg --multiline "#\[test\]\n *fn" ``` -(see the [saftey discussion](https://doc.rust-lang.org/std/env/fn.set_var.html) in -`std::env` for details. +(see the [safety discussion][1] in `std::env` for details). + +[1]: https://doc.rust-lang.org/std/env/fn.set_var.html ## Cluster-specific tests @@ -26,8 +27,9 @@ describes how to run the tests. ## Tutorial tests The tutorial scripts in `doc/src/guide/*.sh` are runnable. These are described in the -documentation using mdBook's anchor feature to include -[portions of files](https://rust-lang.github.io/mdBook/format/mdbook.html) in the +documentation using mdBook's anchor feature to include [portions of files][2] in the documentation as needed. This way, the tutorial can be tested by executing the script. This type of testing validates that the script *runs*, not that it produces the correct output. Developers should manually check the tutorial script output as needed. + +[2]: https://rust-lang.github.io/mdBook/format/mdbook.html diff --git a/doc/src/guide/python/actions.md b/doc/src/guide/python/actions.md index 55d4286..692ba2a 100644 --- a/doc/src/guide/python/actions.md +++ b/doc/src/guide/python/actions.md @@ -8,8 +8,10 @@ This guide will show you how to structure all of your actions in a single file: `actions.py`. This layout is inspired by **row's** predecessor: **signac-flow** and its `project.py`. -> Note: If you are familiar with **signac-fow**, see -> [migrating from signac-flow](../../signac-flow.md) for many helpful tips. +> Note: If you are familiar with **signac-fow**, see [migrating from signac-flow][1] +> for many helpful tips. + +[1]: ../../signac-flow.md To demonstrate the structure of a project, let's build a workflow that computes the sum of squares. The focus of this guide is on structure and best practices. You need to @@ -35,11 +37,12 @@ Execute: ``` to initialize the signac workspace and populate it with directories. -> Note: If you aren't familiar with **signac**, then go read the -> [*basic* tutorial](https://docs.signac.io/en/latest/tutorial.html#basics). Come back -> to the **row** documentation when you get to the section on *workflows*. Or, for -> extra credit, reimplement the **signac** tutorial workflow in **row** after you finish -> reading this guide. +> Note: If you aren't familiar with **signac**, then go read the [*basic* tutorial][2]. +> Come back to the **row** documentation when you get to the section on *workflows*. Or, +> for extra credit, reimplement the **signac** tutorial workflow in **row** after you +> finish reading this guide. + +[2]: https://docs.signac.io/en/latest/tutorial.html#basics ## Write actions.py diff --git a/doc/src/guide/tutorial/index.md b/doc/src/guide/tutorial/index.md index 250aad3..a553a25 100644 --- a/doc/src/guide/tutorial/index.md +++ b/doc/src/guide/tutorial/index.md @@ -2,6 +2,7 @@ This section is a tutorial aimed at users who are new to not only **row**, but also HPC resources in general. It assumes that you have already learned the basics of the shell. -If you are unfamiliar with the shell, check out -[Software Carpentry: The Unix Shell](https://swcarpentry.github.io/shell-novice/) +If you are unfamiliar with the shell, check out [Software Carpentry: The Unix Shell][1] or any other book/tutorial you prefer. + +[1]: https://swcarpentry.github.io/shell-novice/ diff --git a/doc/src/guide/tutorial/submit.md b/doc/src/guide/tutorial/submit.md index 5478ecb..878df65 100644 --- a/doc/src/guide/tutorial/submit.md +++ b/doc/src/guide/tutorial/submit.md @@ -30,10 +30,11 @@ node, GPU, etc...). Your final script must request the correct `--partition` to the command and charge accounts properly. `clusters.toml` describes rules by which **row** automatically selects partitions when it generates job scripts. -> Note: Feel free to ask on the -> [discussion board](https://github.com/glotzerlab/row/discussions) if you need help +> Note: Feel free to ask on the [discussion board][discussion] if you need help > writing configuration files for your cluster. +[discussion]: https://github.com/glotzerlab/row/discussions + Check that the output of `row show cluster` and `row show launchers` is what you expect before continuing. diff --git a/doc/theme/index.hbs b/doc/theme/index.hbs index 03513eb..f86b1c2 100644 --- a/doc/theme/index.hbs +++ b/doc/theme/index.hbs @@ -223,7 +223,7 @@
University of Michigan logo - +
diff --git a/validate/validate.py b/validate/validate.py index 7462d4e..e20a38f 100644 --- a/validate/validate.py +++ b/validate/validate.py @@ -10,12 +10,12 @@ * `cat /output/*.out` The submitted jobs check serial, threaded, MPI, MPI+threads, GPU, and -MPI+GPU jobs to ensure that they run sucessfully and are scheduled to the +MPI+GPU jobs to ensure that they run successfully and are scheduled to the selected resources. Check `*.out` for any error messages. Then check `/output/*.out` for `ERROR`, `WARN`, and `PASSED` lines. `validate.py` prints: `ERROR` when the launched job has a more restrictive binding than requested; `WARN` when the binding is less restrictive; and -'PASSED' when there are at least enough avaialble resources to execute. +'PASSED' when there are at least enough available resources to execute. To test a non-built-in cluster: * Configure your cluster in `cluster.toml`.