From 8e70ea1404d9bca265117ba39c0e0606f82ed8ec Mon Sep 17 00:00:00 2001 From: Antonio Navarro Perez Date: Thu, 7 Oct 2021 19:03:03 +0200 Subject: [PATCH] First version of proper docs. (#79) Signed-off-by: Antonio Navarro Perez --- .github/workflows/mkdocs.yml | 70 +++++++++++ README.md | 114 +----------------- mkdocs/docs/CNAME | 1 + {docs => mkdocs/docs}/images/distribyted.gif | Bin .../docs}/images/distribyted_icon.png | Bin mkdocs/docs/index.md | 93 ++++++++++++++ mkdocs/mkdocs.yml | 26 ++++ mkdocs/requirements.txt | 5 + 8 files changed, 201 insertions(+), 108 deletions(-) create mode 100644 .github/workflows/mkdocs.yml create mode 100644 mkdocs/docs/CNAME rename {docs => mkdocs/docs}/images/distribyted.gif (100%) rename {docs => mkdocs/docs}/images/distribyted_icon.png (100%) create mode 100644 mkdocs/docs/index.md create mode 100644 mkdocs/mkdocs.yml create mode 100644 mkdocs/requirements.txt diff --git a/.github/workflows/mkdocs.yml b/.github/workflows/mkdocs.yml new file mode 100644 index 0000000..5583c84 --- /dev/null +++ b/.github/workflows/mkdocs.yml @@ -0,0 +1,70 @@ +name: MkDocs + +on: + push: + branches: + - master + tags: + - 'v*' + +jobs: + mkdocs: + runs-on: ubuntu-latest + steps: + - name: Checkout code + uses: actions/checkout@v2 + with: + token: ${{ secrets.DEPLOYMENT_PERSONAL_ACCESS_TOKEN }} + # git-revision-date-localized-plugin and mkdocs-rss-plugin need full git history depth + fetch-depth: 0 + + - name: Set up Python + uses: actions/setup-python@v2.2.2 + with: + python-version: "3.x" + + - uses: actions/cache@v2.1.6 + id: cache + with: + path: ~/.cache/pip + key: ${{ runner.os }}-pip-${{ hashFiles('requirements.txt') }} + restore-keys: | + ${{ runner.os }}-pip- + - name: Install dependencies + run: cd mkdocs + run: | + python -m pip install --upgrade pip setuptools wheel + python -m pip install -r requirements.txt + - name: Build docs + run: | + mkdocs build + - name: Validate generated HTML files + run: | + docker run -v $(pwd):/test --rm wjdp/htmltest --conf .htmltest.yml + # On push to master or release branch, deploy docs + - name: Set up git author + if: github.ref == 'refs/heads/master' || startsWith(github.ref, 'refs/heads/release/v') + run: | + remote_repo="https://${GITHUB_TOKEN}@github.com/${GITHUB_REPOSITORY}.git" + git config --global user.name "${GITHUB_ACTOR}" + git config --global user.email "${GITHUB_ACTOR}@users.noreply.github.com" + git remote rm origin + git remote add origin "${remote_repo}" + env: + GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} + + - name: Deploy docs (Latest) + if: github.ref == 'refs/heads/master' + run: | + echo "${CUSTOM_DOMAIN}" > "${GITHUB_WORKSPACE}/mkdocs/docs/CNAME" + echo -e "User-agent: *\nDisallow: /v*.*/\nSitemap: https://${CUSTOM_DOMAIN}/sitemap.xml" > "${GITHUB_WORKSPACE}/docs/robots.txt" + git fetch origin gh-pages --verbose + mike deploy . -t "Cloud (Latest)" --config-file "${GITHUB_WORKSPACE}/mkdocs.yml" --push --rebase + env: + CUSTOM_DOMAIN: docs.codacy.com + + - name: Deploy docs (Self-hosted) + if: startsWith(github.ref, 'refs/heads/release/v') + run: | + git fetch origin gh-pages --verbose + mike deploy ${GITHUB_REF##*/release/} -t "Self-hosted ${GITHUB_REF##*/release/}" --config-file "${GITHUB_WORKSPACE}/mkdocs.yml" --push --rebase \ No newline at end of file diff --git a/README.md b/README.md index 3af30e2..1d5a049 100644 --- a/README.md +++ b/README.md @@ -10,7 +10,7 @@

- Logo + Logo

distribyted

@@ -25,25 +25,6 @@

- -## Table of Contents - -- [Table of Contents](#table-of-contents) -- [About The Project](#about-the-project) - - [Use Cases](#use-cases) - - [Supported _Expandable_ File Formats](#supported-expandable-file-formats) - - [Supported](#supported) - - [To Be Supported](#to-be-supported) - - [Not Supported](#not-supported) -- [Getting Started](#getting-started) - - [Prerequisites on windows](#prerequisites-on-windows) -- [Usage](#usage) - - [Docker](#docker) - - [Configuration File](#configuration-file) -- [Contributing](#contributing) -- [License](#license) - - ## About The Project ![Distribyted Screen Shot][product-screenshot] @@ -76,95 +57,12 @@ Distribyted can show some kind of files directly as folders, making it possible #### Not Supported - gzip: As far as I know, it doesn't support random access. -## Getting Started +## Documentation -Get the latest release from [releases][releases-url] page or download the source code and execute `make build`. - -Run the program: `./distribyted-[VERSION]-[OS]-[ARCH]` - -Defaults are good enough for starters, but you can change them. Here is the output of `./distribyted -help`: - -```text -NAME: - distribyted - Torrent client with on-demand file downloading as a filesystem. - -USAGE: - distribyted [global options] [arguments...] - -GLOBAL OPTIONS: - --config value YAML file containing distribyted configuration. (default: "./distribyted-data/config.yaml") [$DISTRIBYTED_CONFIG] - --http-port value HTTP port for web interface (default: 4444) [$DISTRIBYTED_HTTP_PORT] - --fuse-allow-other Allow other users to acces to all fuse mountpoints. You need to add user_allow_other flag to /etc/fuse.conf file. (default: false) [$DISTRIBYTED_FUSE_ALLOW_OTHER] - --help, -h show help (default: false) -``` - -### Prerequisites on windows - -Download and install [WinFsp](http://www.secfs.net/winfsp/). - -## Usage - -After executing and load all torrent or magnet files, a web interface will be available here: `http://localhost:4444` -It contains information about the mounted routes and torrent files like download/upload speed, leechers, seeders... - -You can also modify the configuration file and reload the server from here: `http://localhost:4444/config` . - -### Docker - -Docker run example: - -```shell -docker run \ - --rm -p 4444:4444 -p 36911:36911 \ - --cap-add SYS_ADMIN \ - --device /dev/fuse \ - --security-opt apparmor:unconfined \ - -v /tmp/mount:/distribyted-data/mount:shared \ - -v /tmp/metadata:/distribyted-data/metadata \ - -v /tmp/config:/distribyted-data/config \ - distribyted/distribyted:latest -``` - -Docker compose example: - -```yaml -distribyted: - container_name: distribyted - image: distribyted/distribyted:latest - restart: always - ports: - - "4444:4444/tcp" - - "36911:36911/tcp" - volumes: - - /home/user/mount:/distribyted-data/mount:shared - - /home/user/metadata:/distribyted-data/metadata - - /home/user/config:/distribyted-data/config - security_opt: - - apparmor:unconfined - devices: - - /dev/fuse - cap_add: - - SYS_ADMIN -``` - -### Configuration File - -You can see the default configuration file with some explanation comments [here](templates/config_template.yaml). - -## Contributing - -Contributions are what make the open-source community such an amazing place to learn, inspire, and create. Any contributions you make are **greatly appreciated**. - -1. Fork the Project -2. Create your Feature Branch (`git checkout -b feature/AmazingFeature`) -3. Commit your changes (`git commit -m 'Add some AmazingFeature'`) -4. Push to the Branch (`git push origin feature/AmazingFeature`) -5. Open a Pull Request - -## License - -Distributed under the GPL3 license. See `LICENSE` for more information. +Check [here][main-url] or [here][doc-folder-url] for further documentation. +[doc-folder-url]: https://github.com/distribyted/distribyted/mkdocs/docs +[main-url]: https://distribyted.com [releases-shield]: https://img.shields.io/github/v/release/distribyted/distribyted.svg?style=flat-square [releases-url]: https://github.com/distribyted/distribyted/releases [docker-pulls-shield]:https://img.shields.io/docker/pulls/distribyted/distribyted.svg?style=flat-square @@ -180,7 +78,7 @@ Distributed under the GPL3 license. See `LICENSE` for more information. [releases-url]: https://github.com/distribyted/distribyted/releases [license-shield]: https://img.shields.io/github/license/distribyted/distribyted.svg?style=flat-square [license-url]: https://github.com/distribyted/distribyted/blob/master/LICENSE -[product-screenshot]: docs/images/distribyted.gif +[product-screenshot]: mkdocs/docs/images/distribyted.gif [example-config]: https://github.com/distribyted/distribyted/blob/master/examples/conf_example.yaml [coveralls-shield]: https://img.shields.io/coveralls/github/distribyted/distribyted?style=flat-square [coveralls-url]: https://coveralls.io/github/distribyted/distribyted diff --git a/mkdocs/docs/CNAME b/mkdocs/docs/CNAME new file mode 100644 index 0000000..f607959 --- /dev/null +++ b/mkdocs/docs/CNAME @@ -0,0 +1 @@ +distribyted.com \ No newline at end of file diff --git a/docs/images/distribyted.gif b/mkdocs/docs/images/distribyted.gif similarity index 100% rename from docs/images/distribyted.gif rename to mkdocs/docs/images/distribyted.gif diff --git a/docs/images/distribyted_icon.png b/mkdocs/docs/images/distribyted_icon.png similarity index 100% rename from docs/images/distribyted_icon.png rename to mkdocs/docs/images/distribyted_icon.png diff --git a/mkdocs/docs/index.md b/mkdocs/docs/index.md new file mode 100644 index 0000000..5a454d8 --- /dev/null +++ b/mkdocs/docs/index.md @@ -0,0 +1,93 @@ +# Main + +## Getting Started + +Get the latest release from [releases][releases-url] page or download the source code and execute `make build`. + +Run the program: `./distribyted-[VERSION]-[OS]-[ARCH]` + +Defaults are good enough for starters, but you can change them. Here is the output of `./distribyted -help`: + +```text +NAME: + distribyted - Torrent client with on-demand file downloading as a filesystem. + +USAGE: + distribyted [global options] [arguments...] + +GLOBAL OPTIONS: + --config value YAML file containing distribyted configuration. (default: "./distribyted-data/config.yaml") [$DISTRIBYTED_CONFIG] + --http-port value HTTP port for web interface (default: 4444) [$DISTRIBYTED_HTTP_PORT] + --fuse-allow-other Allow other users to acces to all fuse mountpoints. You need to add user_allow_other flag to /etc/fuse.conf file. (default: false) [$DISTRIBYTED_FUSE_ALLOW_OTHER] + --help, -h show help (default: false) +``` + +### Prerequisites on windows + +Download and install [WinFsp](http://www.secfs.net/winfsp/). + +## Usage + +After executing and load all torrent or magnet files, a web interface will be available here: `http://localhost:4444` +It contains information about the mounted routes and torrent files like download/upload speed, leechers, seeders... + +You can also modify the configuration file and reload the server from here: `http://localhost:4444/config` . + +### Docker + +Docker run example: + +```shell +docker run \ + --rm -p 4444:4444 -p 36911:36911 \ + --cap-add SYS_ADMIN \ + --device /dev/fuse \ + --security-opt apparmor:unconfined \ + -v /tmp/mount:/distribyted-data/mount:shared \ + -v /tmp/metadata:/distribyted-data/metadata \ + -v /tmp/config:/distribyted-data/config \ + distribyted/distribyted:latest +``` + +Docker compose example: + +```yaml +distribyted: + container_name: distribyted + image: distribyted/distribyted:latest + restart: always + ports: + - "4444:4444/tcp" + - "36911:36911/tcp" + volumes: + - /home/user/mount:/distribyted-data/mount:shared + - /home/user/metadata:/distribyted-data/metadata + - /home/user/config:/distribyted-data/config + security_opt: + - apparmor:unconfined + devices: + - /dev/fuse + cap_add: + - SYS_ADMIN +``` + +### Configuration File + +You can see the default configuration file with some explanation comments [here](https://github.com/distribyted/distribyted/blob/master/templates/config_template.yaml). + +## Contributing + +Contributions are what make the open-source community such an amazing place to learn, inspire, and create. Any contributions you make are **greatly appreciated**. + +1. Fork the Project +2. Create your Feature Branch (`git checkout -b feature/AmazingFeature`) +3. Commit your changes (`git commit -m 'Add some AmazingFeature'`) +4. Push to the Branch (`git push origin feature/AmazingFeature`) +5. Open a Pull Request + +## License + +Distributed under the GPL3 license. See `LICENSE` for more information. + + +[product-screenshot]: images/distribyted.gif diff --git a/mkdocs/mkdocs.yml b/mkdocs/mkdocs.yml new file mode 100644 index 0000000..2df7100 --- /dev/null +++ b/mkdocs/mkdocs.yml @@ -0,0 +1,26 @@ +site_name: Distribyted Documentation +site_url: https://distribyted.com/ +repo_url: https://github.com/distribyted/distribyted +repo_name: distribyted/distribyted +theme: + icon: + repo: fontawesome/brands/github + name: material + palette: + primary: blue + features: + - navigation.instant + - navigation.tracking + - navigation.expand + - navigation.indexes + - toc.integrate + +edit_uri: edit/master/mkdocs/docs/ + +plugins: + - git-revision-date + +extra: + version: + default: latest + provider: mike diff --git a/mkdocs/requirements.txt b/mkdocs/requirements.txt new file mode 100644 index 0000000..61d6bb3 --- /dev/null +++ b/mkdocs/requirements.txt @@ -0,0 +1,5 @@ +mkdocs==1.2.2 +mkdocs-git-revision-date-plugin==0.3.1 +mkdocs-material==7.3.2 +mkdocs-material-extensions==1.0.3 +mike=1.1.2 \ No newline at end of file