Merge pull request #210 from PlasmaFAIR/dev-command

Add basic docs

.cargo/config.toml

@@ -0,0 +1,2 @@
+[alias]
+dev = "run --package fortitude_dev --bin fortitude_dev"

.readthedocs.yml

@@ -0,0 +1,13 @@
+version: 2
+
+build:
+  os: ubuntu-24.04
+  tools:
+    python: "3"
+
+python:
+  install:
+    - requirements: requirements.docs.txt
+
+mkdocs:
+  configuration: mkdocs.yml

Cargo.toml

@@ -1,5 +1,5 @@
 [workspace]
-members = ["fortitude", "fortitude_macros"]
+members = ["fortitude", "fortitude_macros", "fortitude_dev"]
 resolver = "2"
 
 [workspace.package]
@@ -13,8 +13,18 @@ authors = [
 license = "MIT"
 
 [workspace.dependencies]
+fortitude = { path = "fortitude" }
+fortitude_macros = { path = "fortitude_macros" }
+
+anyhow = "1.0.79"
+clap = { version = "4.4.16", features = ["derive", "string", "env"] }
 colored = { version = "2.1.0" }
 itertools = "0.12.0"
+ruff_cache = { git = "https://github.com/astral-sh/ruff.git", tag = "0.7.1", version = "0.0.0" }
+ruff_diagnostics = { git = "https://github.com/astral-sh/ruff.git", tag = "0.7.1", version = "0.0.0" }
+ruff_macros = { git = "https://github.com/astral-sh/ruff.git", tag = "0.7.1", version = "0.0.0" }
+ruff_source_file = { git = "https://github.com/astral-sh/ruff.git", tag = "0.7.1", version = "0.0.0" }
+ruff_text_size = { git = "https://github.com/astral-sh/ruff.git", tag = "0.7.1", version = "0.0.0" }
 serde_json = { version = "1.0.113" }
 strum = { version = "0.26.0", features = ["strum_macros"] }
 strum_macros = { version = "0.26.0" }

README.dev.md

@@ -87,10 +87,20 @@ Once you've completed the code for the rule itself, you can define tests with th
 1. Run `cargo test` again to ensure that your test passes.
 
 
+## Building Docs
+
+The documentation can be built locally using:
+
+```bash
+pip install mkdocs-material
+mkdocs serve
+```
+
 ## Making New Releases
 
 To make a new release, the following steps must be completed in order:
 
+- Make sure the generated docs are up-to-date: `cargo dev generate-all`
 - Make a new commit that updates the project version in `pyproject.toml`,
   `Cargo.toml`, and `CITATION.cff`.
   - Remember to run `cargo build` to update the `Cargo.lock` file too!

README.md

@@ -180,6 +180,10 @@ rules on top of those in the configuration file.
 fortitude check --extend-select=M
 ```
 
+## Documentation
+
+See [table of rules](https://fortitude.readthedocs.io/en/rules/) for a list of all rules.
+
 ## Contributing
 
 Please feel free to add or suggest new rules or comment on the layout of the project

docs/configuration.md

@@ -0,0 +1,102 @@
+# Configuration
+
+Fortitude will look for either a `fortitude.toml` or `fpm.toml` file
+in the current directory, or one of its parents. If using
+`fortitude.toml`, settings should be under the command name, while for
+`fpm.toml` files, this has to be additionally nested under the
+`extra.fortitude` table:
+
+
+=== "fortitude.toml"
+
+    ```toml
+    [check]
+    select = ["S", "T"]
+    ignore = ["S001", "S051"]
+    line-length = 132
+    ```
+=== "fpm.toml"
+
+    ```toml
+    [extra.fortitude.check]
+    select = ["S", "T"]
+    ignore = ["S001", "S051"]
+    line-length = 132
+    ```
+
+You can use `--extend-select` from the command line to select additional
+rules on top of those in the configuration file.
+
+```bash
+# Selects S, T, and M categories
+fortitude check --extend-select=M
+```
+
+## Full command-line interface
+
+See `fortitude help` for the full list of Fortitude's top-level commands:
+
+<!-- Begin auto-generated command help. -->
+
+```text
+A Fortran linter, written in Rust and installable with Python
+
+Usage: fortitude [OPTIONS] <COMMAND>
+
+Commands:
+  check    Perform static analysis on files and report issues
+  explain  Get descriptions, rationales, and solutions for each rule
+  help     Print this message or the help of the given subcommand(s)
+
+Options:
+      --config-file <CONFIG_FILE>  Path to a TOML configuration file
+  -h, --help                       Print help
+  -V, --version                    Print version
+```
+
+<!-- End auto-generated command help. -->
+
+Or `fortitude help check` for more on the linting command:
+
+<!-- Begin auto-generated check help. -->
+
+```text
+Perform static analysis on files and report issues
+
+Usage: fortitude check [OPTIONS] [FILES]...
+
+Arguments:
+  [FILES]...  List of files or directories to check. Directories are searched recursively for Fortran files. The `--file-extensions` option can be used to control which files are included in the search [default: .]
+
+Options:
+      --line-length <LINE_LENGTH>
+          Set the maximum allowable line length [default: 100]
+      --file-extensions <FILE_EXTENSIONS>
+          File extensions to check [default: f90 F90 f95 F95 f03 F03 f08 F08 f18 F18 f23 F23]
+      --fix
+          Apply fixes to resolve lint violations. Use `--no-fix` to disable or `--unsafe-fixes` to include unsafe fixes
+      --unsafe-fixes
+          Include fixes that may not retain the original intent of the code. Use `--no-unsafe-fixes` to disable
+      --show-fixes
+          Show an enumeration of all fixed lint violations. Use `--no-show-fixes` to disable
+      --fix-only
+          Apply fixes to resolve lint violations, but don't report on, or exit non-zero for, leftover violations. Implies `--fix`. Use `--no-fix-only` to disable or `--unsafe-fixes` to include unsafe fixes
+      --output-format <OUTPUT_FORMAT>
+          Output serialization format for violations. The default serialization format is "full" [env: FORTITUDE_OUTPUT_FORMAT=] [possible values: concise, full, json, json-lines, junit, grouped, github, gitlab, pylint, rdjson, azure, sarif]
+      --preview
+          Enable preview mode; checks will include unstable rules and fixes. Use `--no-preview` to disable
+      --progress-bar <PROGRESS_BAR>
+          Progress bar settings. Options are "off" (default), "ascii", and "fancy" [possible values: off, fancy, ascii]
+  -h, --help
+          Print help
+
+Rule selection:
+      --ignore <RULE_CODE>
+          Comma-separated list of rules to ignore
+      --select <RULE_CODE>
+          Comma-separated list of rule codes to enable (or ALL, to enable all rules)
+      --extend-select <RULE_CODE>
+          Like --select, but adds additional rule codes on top of those already specified
+```
+
+<!-- End auto-generated check help. -->

docs/faq.md

@@ -0,0 +1,21 @@
+# FAQ
+
+## Does fortitude handle preprocessor files?
+
+`fortitude` uses the
+[tree-sitter](https://tree-sitter.github.io/tree-sitter/) [Fortran
+grammar](https://github.com/stadelmanma/tree-sitter-fortran) to parse
+your source code, and currently this has some support for the
+preprocessor -- essentially limited to `#include`, and `#if` and
+`#ifdef` guards around complete statements or constructs.
+
+However, tree-sitter is fairly error tolerant, and `fortitude` should
+still run fine, you might just get spurious syntax errors. You can
+ignore these project wide with `--ignore=E001`.
+
+
+## What is "preview"?
+
+Preview enables a collection of newer rules and fixes that are considered experimental or unstable.
+See the [preview documentation](preview.md) for more details; or, to see which rules are currently
+in preview, visit the [rules reference](rules.md).

docs/index.md

@@ -0,0 +1,28 @@
+# Fortitude: A Fortran Linter
+
+A Fortran linter, inspired by (and built upon) [Ruff](https://github.com/astral-sh/ruff).
+Written in Rust :crab: and installable with Python :snake:.
+
+- :zap: Blazingly fast, up to hundreds of times faster than other open-source Fortran
+  linters.
+- :wrench: Automatically fixes linter warnings.
+- :chart_with_upwards_trend: 30+ rules, with many more planned.
+- :page_with_curl: Multiple output formats, including SARIF and GitHub/GitLab CI.
+- :handshake: Follows [community best
+  practices](https://fortran-lang.org/en/learn/best_practices/).
+- :muscle: Built on a robust [tree-sitter](https://tree-sitter.github.io/tree-sitter/)
+  parser -- even syntax errors won't stop it!
+
+## Quickstart
+
+Fortitude can be installed directly into your Python environment:
+
+```console
+$ pip install fortitude-lint
+```
+
+Run Fortitude on your project:
+
+```console
+$ fortitude check
+```

docs/javascript/readthedocs.js

@@ -0,0 +1,32 @@
+document.addEventListener("DOMContentLoaded", function(event) {
+// Trigger Read the Docs' search addon instead of Material MkDocs default
+document.querySelector(".md-search__input").addEventListener("focus", (e) => {
+        const event = new CustomEvent("readthedocs-search-show");
+        document.dispatchEvent(event);
+    });
+});
+
+// Use CustomEvent to generate the version selector
+document.addEventListener(
+        "readthedocs-addons-data-ready",
+        function (event) {
+        const config = event.detail.data();
+        const versioning = `
+<div class="md-version">
+<button class="md-version__current" aria-label="Select version">
+    ${config.versions.current.slug}
+</button>
+
+<ul class="md-version__list">
+${ config.versions.active.map(
+    (version) => `
+    <li class="md-version__item">
+    <a href="${ version.urls.documentation }" class="md-version__link">
+        ${ version.slug }
+    </a>
+            </li>`).join("\n")}
+</ul>
+</div>`;
+
+    document.querySelector(".md-header__topic").insertAdjacentHTML("beforeend", versioning);
+});

docs/overrides/main.html

@@ -0,0 +1,6 @@
+{% extends "base.html" %}
+
+{% block site_meta %}
+{{ super() }}
+<meta name="readthedocs-addons-api-version" content="1" />
+{% endblock %}