mkdocs for docs

.github/workflows/build.yml

@@ -0,0 +1,27 @@
+name: Build site
+
+on:
+  pull_request:
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v10
+        with:
+          enable-cache: true
+
+      - run: uv sync --frozen
+
+      - name: Sync the manuals from the tool repositories
+        run: uv run scripts/sync_upstream_docs.py
+
+      - name: Build
+        run: uv run mkdocs build --strict

.github/workflows/deploy.yml

@@ -0,0 +1,52 @@
+name: Deploy site
+
+on:
+  push:
+    branches: [master]
+  # Pick up manual page changes in the tool repositories once a day.
+  schedule:
+    - cron: "17 4 * * *"
+  workflow_dispatch:
+
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+concurrency:
+  group: pages
+  cancel-in-progress: false
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v10
+        with:
+          enable-cache: true
+
+      - name: Install dependencies
+        run: uv sync --frozen
+
+      - name: Sync the manuals from the tool repositories
+        run: uv run scripts/sync_upstream_docs.py
+
+      - name: Build
+        run: uv run mkdocs build --strict
+
+      - uses: actions/upload-pages-artifact@v5
+        with:
+          path: site
+
+  deploy:
+    needs: build
+    runs-on: ubuntu-latest
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    steps:
+      - id: deployment
+        uses: actions/deploy-pages@v5

.gitignore

@@ -0,0 +1,4 @@
+site/
+.venv/
+__pycache__/
+.cache/

README.md

@@ -0,0 +1,46 @@
+# git-ftp.github.io
+
+The documentation site for both git-ftp implementations,
+[git-ftp-py](https://github.com/git-ftp/git-ftp-py) (Python) and
+[git-ftp](https://github.com/git-ftp/git-ftp) (Bash), published at
+<https://git-ftp.github.io>.
+
+Built with [Material for MkDocs](https://squidfunk.github.io/mkdocs-material/)
+and deployed by GitHub Pages on every push to `master`.
+
+## Working on it
+
+```sh
+uv sync
+uv run mkdocs serve      # http://127.0.0.1:8000
+uv run mkdocs build --strict
+```
+
+## Where the content lives
+
+Everything under `docs/` is written by hand, except the three pages in
+`docs/reference/`. Those are generated from the manual pages in the tool
+repositories:
+
+| Page | Source |
+|---|---|
+| `reference/manual-python.md` | `git-ftp-py:docs/git-ftp.1.md` |
+| `reference/manual-bash.md` | `git-ftp:man/git-ftp.1.md` |
+| `reference/compatibility.md` | `git-ftp-py:COMPATIBILITY.md` |
+
+```sh
+uv run scripts/sync_upstream_docs.py            # fetch from GitHub
+uv run scripts/sync_upstream_docs.py --local    # from ../git-ftp, ../git-ftp-py
+uv run scripts/sync_upstream_docs.py --check    # fail if they are outdated
+```
+
+The deploy workflow runs the sync before every build, and once a day on a
+schedule, so a manual page fixed upstream appears here without a commit in this
+repository. Fix those pages upstream, not here.
+
+## Deployment
+
+`.github/workflows/deploy.yml` builds the site and publishes it with
+`actions/deploy-pages`. This needs **Settings → Pages → Source: GitHub
+Actions** in the repository settings; no `gh-pages` branch is involved.
+`.github/workflows/build.yml` builds pull requests without deploying.

docs/about/contributing.md

@@ -0,0 +1,96 @@
+---
+title: Contributing
+---
+
+# Contributing
+
+Both implementations are maintained on GitHub, and both take patches.
+
+<div class="grid cards" markdown>
+
+-   :fontawesome-brands-python: **[git-ftp-py][py]**
+
+    ---
+
+    The Python implementation.
+
+    [Issues][py-issues] · [Pull requests][py-prs] · [Changelog][py-changelog]
+
+-   :material-bash: **[git-ftp][sh]**
+
+    ---
+
+    The original Bash implementation.
+
+    [Issues][sh-issues] · [Pull requests][sh-prs] · [Changelog][sh-changelog]
+
+</div>
+
+## Reporting a bug
+
+Include the command you ran, the output of `git ftp push -vv` with credentials
+removed, the version (`git ftp --version`) and the server software if you know
+it. FTP servers differ wildly in what they accept, so naming yours often solves
+the riddle straight away.
+
+## Working on the Python implementation
+
+```sh
+git clone https://github.com/git-ftp/git-ftp-py.git
+cd git-ftp-py
+uv sync --all-groups
+make lint typecheck test     # ruff, mypy, pytest
+make test-docker             # against pure-ftpd containers, Linux only
+```
+
+The test suite starts real FTP, FTPS and SFTP servers in-process, so most
+changes can be covered by a test without any server of your own. The manual
+page source is `docs/git-ftp.1.md`.
+
+Anything that changes behaviour compared to the Bash original belongs in
+`COMPATIBILITY.md` — that file is the contract between the two implementations
+and is published [here](../reference/compatibility.md).
+
+## Working on the Bash implementation
+
+```sh
+git clone https://github.com/git-ftp/git-ftp.git
+cd git-ftp
+make test
+```
+
+The core functionality is unit tested with
+[shunit2](https://github.com/kward/shunit2); the tests are in `tests/`. The
+manual page source is `man/git-ftp.1.md`.
+
+Add yourself to the [AUTHORS](https://github.com/git-ftp/git-ftp/blob/master/AUTHORS)
+file with your first patch.
+
+## This website
+
+The site is built with [MkDocs](https://www.mkdocs.org/) and
+[Material for MkDocs](https://squidfunk.github.io/mkdocs-material/) from the
+[git-ftp.github.io](https://github.com/git-ftp/git-ftp.github.io) repository
+and published by GitHub Pages on every push.
+
+```sh
+git clone https://github.com/git-ftp/git-ftp.github.io.git
+cd git-ftp.github.io
+uv sync
+uv run mkdocs serve
+```
+
+The three reference pages are generated from the tool repositories by
+`scripts/sync_upstream_docs.py` and refreshed at build time — fix a manual page
+upstream, not here. Everything else under `docs/` is written by hand; there is
+an :material-pencil: link at the top of every page that takes you straight to
+its source.
+
+[py]: https://github.com/git-ftp/git-ftp-py
+[py-issues]: https://github.com/git-ftp/git-ftp-py/issues
+[py-prs]: https://github.com/git-ftp/git-ftp-py/pulls
+[py-changelog]: https://github.com/git-ftp/git-ftp-py/blob/main/CHANGELOG.md
+[sh]: https://github.com/git-ftp/git-ftp
+[sh-issues]: https://github.com/git-ftp/git-ftp/issues
+[sh-prs]: https://github.com/git-ftp/git-ftp/pulls
+[sh-changelog]: https://github.com/git-ftp/git-ftp/blob/master/CHANGELOG.md

docs/about/license.md

@@ -0,0 +1,31 @@
+---
+title: License
+---
+
+# License
+
+Both implementations of git-ftp are free software, licensed under the
+[GNU General Public License, Version 3.0](https://www.gnu.org/licenses/gpl-3.0-standalone.html)
+or later.
+
+- [LICENSE — git-ftp (Python)](https://github.com/git-ftp/git-ftp-py/blob/main/LICENSE)
+- [LICENSE — git-ftp (Bash)](https://github.com/git-ftp/git-ftp/blob/master/LICENSE)
+
+This means you may use, study, share and modify git-ftp, and that anything you
+distribute based on it carries the same freedoms.
+
+## Authors
+
+git-ftp was started by René Moser and has since been maintained with
+[Maikel Linke](https://github.com/mlinke-ai) and a long list of contributors on
+GitHub. The Python port is written by René Moser and the git-ftp contributors.
+
+The [AUTHORS](https://github.com/git-ftp/git-ftp/blob/master/AUTHORS) file has
+an (incomplete) list of everyone who helped. Add yourself when you send a
+patch.
+
+## This documentation
+
+The contents of this site are part of the
+[git-ftp.github.io](https://github.com/git-ftp/git-ftp.github.io) repository
+and are covered by the same license.

docs/getting-started/first-deployment.md

@@ -0,0 +1,102 @@
+---
+title: First deployment
+---
+
+# First deployment
+
+## 1. Tell git-ftp where the server is
+
+Run this once inside your repository:
+
+```sh
+git config git-ftp.url "ftp://example.com/public_html"
+git config git-ftp.user "alice"
+git config git-ftp.password "s3cret"
+```
+
+The settings land in `.git/config`, which is not part of the repository, so the
+password is not committed. If you would rather not store it at all, see
+[credentials](../guide/protocols.md#credentials) for `-P`, `--password-command`,
+`~/.netrc`, the macOS keychain and environment variables.
+
+## 2. Upload everything once
+
+If the server is empty, or its contents should be replaced by what is in Git:
+
+```sh
+git ftp init
+```
+
+This uploads every tracked file that is not ignored and writes the commit id
+into `.git-ftp.log` on the server.
+
+If the files are **already** on the server and match your working tree, do not
+upload them again — just record the commit:
+
+```sh
+git ftp catchup
+```
+
+!!! tip "Look before you leap"
+
+    `--dry-run` prints what would be transferred and touches nothing:
+
+    ```sh
+    git ftp init --dry-run
+    ```
+
+## 3. Deploy your changes
+
+From now on, every deployment is one command:
+
+```sh
+echo "new content" >> index.txt
+git commit index.txt -m "Add new content"
+git ftp push
+```
+
+```text
+1 file to sync:
+[1 of 1] Buffered for upload 'index.txt'.
+Uploading ...
+Last deployment changed from 1f2a3b4 to ded01b2.
+```
+
+git-ftp reads the commit recorded on the server, diffs it against `HEAD` and
+transfers exactly the files that were added, changed or deleted. Only when
+every upload succeeded does it update the log, so an interrupted deployment
+never claims a commit it did not finish.
+
+## 4. Check what is deployed
+
+```sh
+git ftp show     # git show of the deployed commit
+git ftp log      # git log starting at the deployed commit
+```
+
+## Going back, and other branches
+
+Because the state on the server is just a commit, moving around in history is
+ordinary Git work:
+
+```sh
+# deploy the state of three commits ago
+git checkout HEAD~3
+git ftp push
+
+# deploy another branch without checking it out
+git ftp push -b staging
+
+# upload the difference between develop and master
+git checkout develop
+git ftp push --commit master
+```
+
+## Where to go next
+
+- [Configuration](../guide/configuration.md) — every setting, and where to put it.
+- [Scopes](../guide/scopes.md) — staging and production in one repository.
+- [Selecting files](../guide/selecting-files.md) — `.git-ftp-ignore`,
+  `.git-ftp-include`, `--syncroot`.
+- [Continuous deployment](../guide/ci-cd.md) — deploy from GitHub Actions,
+  GitLab CI or Bitbucket Pipelines.