Skip to content

Commit

Permalink
chore: Improve docs (#206)
Browse files Browse the repository at this point in the history 
* chore: Improve docs

* chore: Improve `FAQ.md`

* chore: Improve `FAQ.md`
  • Loading branch information
@kurosakishigure
kurosakishigure authored Jan 2, 2025
1 parent 4541024 commit 8ae18fc
Show file tree
Hide file tree
Showing 3 changed files with 49 additions and 39 deletions.
16 changes: 13 additions & 3 deletions docs/FAQ.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -2,18 +2,28 @@

## Encountering System Security Policy on First Run of Katharsis on macOS

### Plan 1

When you first run Katharsis on macOS, you might see a system security warning that looks like this:

![Not Opened](../assets/faq/not_opened.png)

This happens because the Katharsis binary was not signed with an Apple Developer Certificate during its build process in the [Actions](https://github.com/kurosakishigure/katharsis/actions/workflows/cd.yml). To resolve this issue, you can use the following steps:
This happens because the Katharsis binary was not signed with an [Apple Developer Certificate](https://developer.apple.com/support/certificates) during its build process in the [Actions](https://github.com/kurosakishigure/katharsis/actions/workflows/cd.yml).

> We plan to use artifact attestations to establish provenance for builds. For more details, see [#73](https://github.com/kurosakishigure/katharsis/issues/73).
### Plan 1

You can use the following operations:

![Allow Anyway](../assets/faq/allow_anyway.png)

### Plan 2

You can refer to the **Cargo** section in [USE.md](https://github.com/kurosakishigure/katharsis/blob/canary/docs/USE.md#linux-and-macos) to install Katharsis.

> Please **ensure** that the Cargo package manager is installed.
### Plan 3

If you prefer, you can also choose to install from source. For detailed instructions, please refer to [INSTALL.md](INSTALL.md).

> In the future, we plan to address this problem by enabling installation of Katharsis through package managers like [brew](https://brew.sh). If you're interested in helping us implement this feature, you can contribute by following the guidelines in [CONTRIBUTING.md](../.github/CONTRIBUTING.md).
10 changes: 6 additions & 4 deletions docs/INSTALL.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -2,7 +2,9 @@

## Ensure Rust Toolchain is Installed

First, make sure that you have the Rust toolchain installed. If you haven’t installed it yet, visit the [official Rust website](https://www.rust-lang.org) and follow the instructions to install Rust and Cargo.
First, make sure that you have the Rust toolchain installed.

> If you haven’t installed it yet, visit the [official Rust website](https://www.rust-lang.org) and follow the instructions to install Rust and Cargo.
You can check if Rust and Cargo are installed by running:

Expand All @@ -21,9 +23,9 @@ Open a terminal and navigate to the root directory of the Katharsis project you
cd /path/to/your/katharsis/project
```

## Install and build the project.
## Install and Build the Project

To install the dependencies specified in the Cargo.toml file, run the following command:
To install the dependencies specified in the `Cargo.toml` file, run the following command:

```bash
cargo build --release
Expand All @@ -32,7 +34,7 @@ cargo build --release
> - This command not only installs the dependencies but also builds the project.
> - You can run the `cd target/release` command in the root directory of the project to find the katharsis executable file in the release folder.
## Run Tests (Optional)
## Run Unit Tests (optional)

Run the unit tests to ensure that everything in the project is functioning correctly:

Expand Down
62 changes: 30 additions & 32 deletions docs/USE.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -4,17 +4,7 @@

### Linux and macOS

First, download the appropriate binary from the [Releases](https://github.com/kurosakishigure/katharsis/releases/latest) page.

> You can find the platform comparison table in the [Platform Support](https://doc.rust-lang.org/rustc/platform-support.html) section.
If you're using a Debian-based system, you can directly install the .deb file from the download directory using apt:

```bash
sudo apt install katharsis.deb
```

If you're using Cargo, please run:
If you're using **Cargo**, please run:

```bash
cargo install katharsis
Expand All @@ -34,7 +24,16 @@ cargo binstall katharsis
> - You might also need to add the environment variable `export PATH=$HOME/.cargo/bin:$PATH` to your `.zshrc` or `.bashrc` file.
> - If you choose to use `cargo binstall katharsis`, you might need to run `brew install cargo-binstall` first.
Otherwise, you'll need to follow the step-by-step instructions below to install Katharsis.
If you're using a **Debian-based system**, you can directly install the `.deb` file from the download directory using `apt`:
```bash
sudo apt install katharsis.deb
```
> - Download the appropriate binary from the [Releases](https://github.com/kurosakishigure/katharsis/releases/latest) page.
> - You can find the platform comparison table in the [Platform Support](https://doc.rust-lang.org/rustc/platform-support.html) section.
Otherwise, you'll need to follow the **step-by-step** instructions below to install Katharsis.
Run the following command to extract the downloaded file:
Expand All @@ -48,20 +47,20 @@ Next, execute the following command in your home directory to create the necessa
mkdir -p Formulae/bin
```

Move the downloaded binary to ~/Formulae/bin:
Move the downloaded binary to `~/Formulae/bin`:

```bash
mv ~/your/extract/path/katharsis ~/Formulae/bin/katharsis
```

Modify your .zshrc or .bashrc file by adding the following configuration:
Modify your `.zshrc` or `.bashrc` file by adding the following configuration:

```bash
# Formulae
export PATH=$HOME/Formulae/bin:$PATH
```

> Typing `katharsis` might be cumbersome, so you can use a shorter alias like `rss` in your .zshrc or .bashrc file instead:
> Typing `katharsis` might be cumbersome, so you can use a shorter alias like `rss` in your `.zshrc` or `.bashrc` file instead:
>
> ```bash
> alias rss=katharsis
Expand Down Expand Up @@ -95,22 +94,22 @@ For a detailed explanation of the fields in the `katharsis.config.toml` file, re

## Command Overview

| Command | Description |
|---------|------------------------------------------------------------------|
| init | Generates a katharsis.config.toml file in the current directory. |
| help | Displays help information. |
| Command | Description |
|---------|--------------------------------------------------------------------|
| init | Generates a `katharsis.config.toml` file in the current directory. |
| help | Displays help information. |

## Parameter Overview

| Parameter | Description |
|-----------|--------------------------------------------------------------|
| -c | Specifies a katharsis.config.toml file as the configuration. |
| -h | Displays help information. |
| -V | Displays the current version of Katharsis. |
| Parameter | Description |
|-----------|----------------------------------------------------------------|
| -c | Specifies a `katharsis.config.toml` file as the configuration. |
| -h | Displays help information. |
| -V | Displays the current version of Katharsis. |

> If you do not specify the `-c` parameter, the `katharsis.config.toml` file in the current directory will be used by default.
## Explanation of katharsis.config.toml Fields
## Explanation of `katharsis.config.toml` Fields

You can refer to the [RSS 2.0 at Harvard Law](https://cyber.harvard.edu/rss/rss.html) for more detailed documentation.

Expand All @@ -127,10 +126,9 @@ You can refer to the [RSS 2.0 at Harvard Law](https://cyber.harvard.edu/rss/rss.
| output | Path to the local output RSS file. |

> [!NOTE]
> - The site_url field should not include a trailing slash (e.g., https://example.com rather than https://example.com/).
> - The image field is relative to the site_url, for example, favicon.png corresponds
to https://example.com/favicon.png.
> - The output field specifies the path relative to the working directory (e.g., rss.xml corresponds to ./rss.xml).
> - The `site_url` field should not include a trailing slash (e.g., `https://example.com` rather than `https://example.com/`).
> - The `image` field is relative to the `site_url`, for example, `favicon.png` corresponds to `https://example.com/favicon.png`.
> - The `output` field specifies the path relative to the working directory (e.g., `rss.xml` corresponds to `./rss.xml`).
### article

Expand All @@ -147,6 +145,6 @@ You can refer to the [RSS 2.0 at Harvard Law](https://cyber.harvard.edu/rss/rss.
| sort | Whether to sort articles by their publication date. |

> [!NOTE]
> - The input field corresponds to the file body, which is the same as the article's URL slug.
> - The date field's tag must include a [datetime](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/time) attribute, and the attribute value must follow the `%Y-%m-%d` format.
> - The image field’s folder name must match the article's URL slug.
> - The `input` field corresponds to the file stem(`*`), which is the same as the article's URL slug.
> - The `date` field's tag must include a [datetime](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/time) attribute, and the attribute value must follow the `%Y-%m-%d` format.
> - The `image` field’s folder name(`**`) must match the article's URL slug.

0 comments on commit 8ae18fc

Please sign in to comment.