docs: adjust dev doc file structure, add build and deploy docs (#804)

* docs: add separate section on development

* docs: update instructions on writing docs

* docs: add build and deploy docs

.gitignore

@@ -34,4 +34,3 @@ deny.toml
 
 # mkdocs
 site/
-docs/site

docs/.gitignore

@@ -0,0 +1,2 @@
+site/
+venv/

docs/content/contribution/development.md

@@ -1,11 +0,0 @@
-# Development
-
-!!! Warning
-
-    This section is currently WIP.
-
-## Dev Environment
-
-## Logging
-
-## Testing

docs/content/contribution/development/build_process.md

@@ -0,0 +1,63 @@
+# Build Process
+
+!!! Warning
+
+    This section is currently somewhat WIP.
+
+!!! Warning
+
+    This section is intended for people who wish to work on/build/distribute bottom, not general users.
+
+## Overview
+
+bottom manages its own binary builds for nightly and stable release purposes. The core build workflow is handled by [`build_releases.yml`](https://github.com/ClementTsang/bottom/blob/master/.github/workflows/build_releases.yml), called by a wrapper workflow for [nightly](https://github.com/ClementTsang/bottom/blob/master/.github/workflows/nightly.yml) and [stable](https://github.com/ClementTsang/bottom/blob/master/.github/workflows/deployment.yml) releases. Builds take place via GitHub Actions.
+
+The main things built are:
+
+- Binaries for various platforms
+- MSI installer for Windows
+- `.deb` package for Debian and its derivatives
+
+This documentation gives a high-level overview of the build process for each part. For the most up-to-date and detailed reference, definitely refer back to the [`build_releases.yml`](https://github.com/ClementTsang/bottom/blob/master/.github/workflows/build_releases.yml) file.
+
+## Binaries
+
+Binaries are built currently for various targets. Note that not all of these are officially supported. The following general steps are performed:
+
+- Set up the Rust toolchain for the action runner.
+- Enable cache.
+- Build a release build with:
+
+  - `--features deploy`, which disables unneeded dev features in bottom.
+  - `--locked` to lock the dependency versions.
+  - The following env variables set:
+
+    - `BTM_GENERATE: true`
+    - `COMPLETION_DIR: "target/tmp/bottom/completion/"`
+    - `MANPAGE_DIR: "target/tmp/bottom/manpage/"`
+
+    These generate the manpages and shell completions (see [Packaging](packaging-and-distribution.md) for some more information).
+
+- Bundle the binaries and manpage/completions.
+- Cleanup.
+
+Some builds use [`cross`](https://github.com/cross-rs/cross) to do cross-compilation builds for architectures otherwise not natively supported by the runner.
+
+## MSI
+
+This builds a full Windows installer using [`cargo-wix`](https://github.com/volks73/cargo-wix). This requires some setup beforehand with some dependencies:
+
+- Net-Framework-Core (handled by Powershell)
+- wixtoolset (handled by chocolatey)
+- Rust toolchain
+
+After that, cache is enabled, and `cargo wix` takes care of the rest.
+
+## `.deb`
+
+Currently, `.deb` files are built for x86 and ARM architectures (`armv7`, `aarch64`). This is handled by [`cargo-deb`](https://crates.io/crates/cargo-deb).
+
+- For x86, this is handled natively with just `cargo-deb`.
+- For ARM, this uses a Docker container, [cargo-deb-arm](https://github.com/ClementTsang/cargo-deb-arm), which correctly sets the dependencies and architecture for the generated `.deb` file.
+
+There are additional checks via `dpkg` to ensure the architecture is correctly set.

docs/content/contribution/development/deploy_process.md

@@ -0,0 +1,53 @@
+# Deploy Process
+
+!!! Warning
+
+    This section is currently WIP.
+
+!!! Warning
+
+    This section is intended for people who wish to work on/build/distribute bottom, not general users.
+
+## Overview
+
+bottom currently has two main deploy processes to worry about:
+
+- [Nightly](https://github.com/ClementTsang/bottom/blob/master/.github/workflows/nightly.yml): a daily (00:00 UTC) GitHub action to build binary/installer files, and upload them to the [nightly release](https://github.com/ClementTsang/bottom/releases/tag/nightly). It can also be triggered manually as either a proper nightly release or a mock release.
+- [Stable](https://github.com/ClementTsang/bottom/blob/master/.github/workflows/deployment.yml): a stable deployment, triggered manually or upon creation of a valid tag. This is a GitHub action that builds binary/installer files and uploads them to a new GitHub release.
+
+  Furthermore, this workflow does not handle the following deployments, which must be manually handled:
+
+  - [Chocolatey](https://community.chocolatey.org/packages/bottom)
+  - [crates.io](https://crates.io/crates/bottom)
+
+## Nightly
+
+This is, for the most part, automatic, though it can also be used as a way of testing build workflow changes and seeing if binaries can be successfully built at all against all the targets we want to build for.
+
+If one does not want to actually update the nightly release, and just want to test the general builds and workflow, one can run the workflow manually on a branch of choice with "mock" set as the parameter. Changing it to anything else will trigger a non-mock run.
+
+## Stable
+
+This can be manually triggered, though the general use-case is setting a tag of the form `x.y.z` (after checking everything is good, of course). For example:
+
+```bash
+git tag 0.6.9 && git push origin 0.6.9
+```
+
+This will automatically trigger the deployment workflow, and create a draft release with the files uploaded. One still needs to fill in the details and release it.
+
+Furthermore, there are some deployments that are handled by maintainers of bottom that this workflow does not automatically finish. These must be manually handled.
+
+### Chocolatey
+
+Upon releasing on GitHub, [choco-bottom](https://github.com/ClementTsang/choco-bottom) will automatically be updated with a new PR with the correct deployment files for Chocolatey. Check the PR, merge it if it is correct, then pull locally and deploy following the instructions in the [README](https://github.com/ClementTsang/choco-bottom/blob/master/README.md). Make sure to test installation and running at least once before deploying!
+
+If done correctly, there should be a new build on Chocolatey, which will take some time to validate.
+
+### crates.io
+
+Validate everything builds properly and works (you should have done this before releasing though). If good, then deploying on crates.io is as simple as:
+
+```bash
+cargo publish
+```

docs/content/contribution/development/dev_env.md

@@ -0,0 +1,9 @@
+# Development Environment
+
+!!! Warning
+
+    This section is currently WIP.
+
+!!! Warning
+
+    This section is intended for people who wish to work on/build/distribute bottom, not general users.

docs/content/contribution/development/logging.md

@@ -0,0 +1,9 @@
+# Logging
+
+!!! Warning
+
+    This section is currently WIP.
+
+!!! Warning
+
+    This section is intended for people who wish to work on/build/distribute bottom, not general users.

docs/content/contribution/development/testing.md

@@ -0,0 +1,9 @@
+# Testing
+
+!!! Warning
+
+    This section is currently WIP.
+
+!!! Warning
+
+    This section is intended for people who wish to work on/build/distribute bottom, not general users.

docs/content/contribution/documentation.md

@@ -20,12 +20,33 @@ There are a few areas where documentation changes are often needed:
 
 2. Where you're adding documentation will probably affect what you need to do:
 
-   - For changes to [`README.md`](https://github.com/ClementTsang/bottom/blob/master/README.md) and [`CHANGELOG.md`](https://github.com/ClementTsang/bottom/blob/master/CHANGELOG.md), just follow the formatting provided and use any editor.
+   ### `README.md` or `CHANGELOG.md`
 
-   - For changes to the help menu, try to refer to the existing code within `src/constants.rs` on how the help menu is generated.
+   For changes to [`README.md`](https://github.com/ClementTsang/bottom/blob/master/README.md) and [`CHANGELOG.md`](https://github.com/ClementTsang/bottom/blob/master/CHANGELOG.md), just follow the formatting provided and use any editor.
 
-   - For changes to the extended documentation, you'll want [MkDocs](https://www.mkdocs.org/), [Material for MkDocs](https://squidfunk.github.io/mkdocs-material/), and `mdx_truly_sane_lists` installed to provide live reloading and preview for your changes. You can do so through `pip` or your system's package managers. While you don't _need_ these, it'll probably help in making and validating changes.
+   ### Help menu
 
-     You may also want [Mike](https://github.com/jimporter/mike), but it isn't really needed.
+   For changes to the help menu, try to refer to the existing code within `src/constants.rs` on how the help menu is generated.
+
+   ### Extended documentation
+
+   For changes to the extended documentation, you'll probably want [MkDocs](https://www.mkdocs.org/), [Material for MkDocs](https://squidfunk.github.io/mkdocs-material/), `mdx_truly_sane_lists`, and optionally [Mike](https://github.com/jimporter/mike) installed to provide live reloading and preview for your changes. They aren't needed but it'll help with validating your changes.
+
+   You can do so through `pip` or your system's package managers. If you use `pip`, you probably would want to do something like so through a venv:
+
+   ```bash
+   # Starting from the repo root:
+   cd docs/
+
+   # Create venv and activate
+   python -m venv venv
+   source venv/bin/activate
+
+   # Install requirements
+   pip install -r requirements.txt
+
+   # Run mkdocs
+   venv/bin/mkdocs serve
+   ```
 
 3. Once you have your documentation changes done, submit it as a pull request. For more information regarding that, refer to [Issues, Pull Requests, and Discussions](../issues-and-pull-requests/).

docs/content/contribution/issues-and-pull-requests.md

@@ -1,7 +1,5 @@
 # Issues, Pull Requests, and Discussions
 
-Contribution in any way is appreciated, whether it is reporting problems, fixing bugs, implementing features, improving the documentation, etc.
-
 ## Discussions
 
 Discussions are open [in the repo](https://github.com/ClementTsang/bottom/discussions). As for the difference between discussions and issues:

docs/mkdocs.yml

@@ -5,7 +5,6 @@ site_url: https://clementtsang.github.io/bottom
 site_description: >-
   A customizable cross-platform graphical process/system monitor for the terminal. Supports Linux, macOS, and Windows.
 docs_dir: "content/"
-
 # Project information
 repo_name: ClementTsang/bottom
 repo_url: https://github.com/ClementTsang/bottom
@@ -149,6 +148,11 @@ nav:
   - "Contribution":
       - "Issues, Pull Requests, and Discussions": contribution/issues-and-pull-requests.md
       - "Documentation": contribution/documentation.md
-      - "Development": contribution/development.md
       - "Packaging and Distribution": contribution/packaging-and-distribution.md
+      - "Development":
+          - "Development Environment": contribution/development/dev_env.md
+          - "Testing": contribution/development/testing.md
+          - "Logging": contribution/development/logging.md
+          - "Build Process": contribution/development/build_process.md
+          - "Deploy Process": contribution/development/deploy_process.md
   - "Troubleshooting": troubleshooting.md

docs/requirements.txt

@@ -1,5 +1,5 @@
 mkdocs == 1.3.1
 mkdocs-material == 8.4.0
 mkdocs-material-extensions == 1.0.3
-mdx_truly_sane_lists == 1.2
+mdx_truly_sane_lists == 1.3
 mike == 1.1.2