From 0a96f836b7d8632e575137e20640aea2f013b227 Mon Sep 17 00:00:00 2001 From: Antonio Navarro Perez Date: Fri, 8 Oct 2021 11:52:37 +0200 Subject: [PATCH] Organize docs. (#80) --- README.md | 37 +++++----- mkdocs/docs/api-reference.md | 1 + mkdocs/docs/architecture.md | 1 + mkdocs/docs/getting-started.md | 76 +++++++++++++++++++++ mkdocs/docs/index.md | 121 +++++++++------------------------ mkdocs/docs/tutorials.md | 1 + mkdocs/mkdocs.yml | 18 ++++- 7 files changed, 145 insertions(+), 110 deletions(-) create mode 100644 mkdocs/docs/api-reference.md create mode 100644 mkdocs/docs/architecture.md create mode 100644 mkdocs/docs/getting-started.md create mode 100644 mkdocs/docs/tutorials.md diff --git a/README.md b/README.md index faafbf2..a988959 100644 --- a/README.md +++ b/README.md @@ -29,38 +29,37 @@ ![Distribyted Screen Shot][product-screenshot] -Distribyted tries to make easier integrations with other applications among torrent files, presenting them as a standard filesystem. +Distribyted is an alternative torrent client. +It can expose torrent files as a standard FUSE mount or webDAV endpoint and download them on demand, allowing random reads using a fixed amount of disk space. -We aim to use some compressed file characteristics to avoid download it entirely, just the parts that we'll need. - -Also, if the file format is not supported, distribyted can stream and seek through the file if needed. +Distribyted tries to make easier integrations with other applications using torrent files, presenting them as a standard filesystem. **Note that distribyted is in alpha version, it is a proof of concept with a lot of bugs.** -### Use Cases +## Use Cases - Play **multimedia files** on your favorite video or audio player. These files will be downloaded on demand and only the needed parts. - Explore TBs of data from public **datasets** only downloading the parts you need. Use **Jupyter Notebooks** directly to process or analyze this data. - Play your **ROM backups** directly from the torrent file. You can have virtually GBs in games and only downloaded the needed ones. -### Supported _Expandable_ File Formats -Distribyted can show some kind of files directly as folders, making it possible for applications read only the parts that they need. Here is a list of supported, to be supported and not supported formats. - -#### Supported -- zip: Able to uncompress just one file. The file is decompressed to a temporal file sequentially to make possible seek over it. The decompression stops if no one is reading it. - -#### To Be Supported -- tar: Seek to any file and inside that files using a [modified standard library](https://github.com/ajnavarro/go-tar). Not useful on `.tar.gz` files. -- 7zip: Similar to Zip. Need for a library similar to [zip](https://github.com/saracen/go7z). -- xz: Only worth it when the file is created using blocks. Possible library [here](https://github.com/ulikunitz/xz) and [here](https://github.com/frrad/bxzf). - -#### Not Supported -- gzip: As far as I know, it doesn't support random access. - ## Documentation Check [here][main-url] or [here][doc-folder-url] for further documentation. +## 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. + [doc-folder-url]: https://github.com/distribyted/distribyted/blob/master/mkdocs/docs/index.md [main-url]: https://distribyted.com [releases-shield]: https://img.shields.io/github/v/release/distribyted/distribyted.svg?style=flat-square diff --git a/mkdocs/docs/api-reference.md b/mkdocs/docs/api-reference.md new file mode 100644 index 0000000..2fd9f95 --- /dev/null +++ b/mkdocs/docs/api-reference.md @@ -0,0 +1 @@ +TBD \ No newline at end of file diff --git a/mkdocs/docs/architecture.md b/mkdocs/docs/architecture.md new file mode 100644 index 0000000..2fd9f95 --- /dev/null +++ b/mkdocs/docs/architecture.md @@ -0,0 +1 @@ +TBD \ No newline at end of file diff --git a/mkdocs/docs/getting-started.md b/mkdocs/docs/getting-started.md new file mode 100644 index 0000000..afb7c9a --- /dev/null +++ b/mkdocs/docs/getting-started.md @@ -0,0 +1,76 @@ +## Installation + +### Using the binary + +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/). + +### Using 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 +``` + +## Usage + +After executing and load all torrent or magnet files, a web interface will be available at `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 `http://localhost:4444/config` . + +### 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). \ No newline at end of file diff --git a/mkdocs/docs/index.md b/mkdocs/docs/index.md index 5a454d8..d91931d 100644 --- a/mkdocs/docs/index.md +++ b/mkdocs/docs/index.md @@ -1,93 +1,36 @@ -# 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. +Distribyted is an alternative torrent client. +It can expose torrent files as a standard FUSE mount or webDAV endpoint and download them on demand, allowing random reads using a fixed amount of disk space. +![Distribyted Screen Shot][product-screenshot] [product-screenshot]: images/distribyted.gif + + +## Features + +### User Interfaces + +Distribyted supports several ways to expose the files to the user or external applications: + +#### Supported + +- FUSE: Other applications can access to torrent files directly as a filesystem. +- WebDAV: Applications that supports WebDAV can access torrent files using this protocol. It is recommended when distribyted is running in a remote machine or using docker. + +#### To be supported +- HTTP: distribyted will support direct HTTP access to files. + +### _Expandable_ File Formats +Distribyted can show some kind of files directly as folders, making it possible for applications read only the parts that they need. Here is a list of supported, to be supported and not supported formats. + +#### Supported +- zip: Able to uncompress just one file. The file is decompressed to a temporal file sequentially to make possible seek over it. The decompression stops if no one is reading it. + +#### To Be Supported +- tar: Seek to any file and inside that files using a [modified standard library](https://github.com/ajnavarro/go-tar). Not useful on `.tar.gz` files. +- 7zip: Similar to Zip. Need for a library similar to [zip](https://github.com/saracen/go7z). +- xz: Only worth it when the file is created using blocks. Possible library [here](https://github.com/ulikunitz/xz) and [here](https://github.com/frrad/bxzf). + +#### Not Supported +- gzip: As far as I know, it doesn't support random access. diff --git a/mkdocs/docs/tutorials.md b/mkdocs/docs/tutorials.md new file mode 100644 index 0000000..2fd9f95 --- /dev/null +++ b/mkdocs/docs/tutorials.md @@ -0,0 +1 @@ +TBD \ No newline at end of file diff --git a/mkdocs/mkdocs.yml b/mkdocs/mkdocs.yml index 2df7100..1b588d8 100644 --- a/mkdocs/mkdocs.yml +++ b/mkdocs/mkdocs.yml @@ -1,18 +1,28 @@ -site_name: Distribyted Documentation +site_name: Distribyted site_url: https://distribyted.com/ repo_url: https://github.com/distribyted/distribyted repo_name: distribyted/distribyted + +nav: + - Home: index.md + - Getting Started: getting-started.md + - Tutorials: tutorials.md + - API Reference: api-reference.md + theme: + logo: images/distribyted_icon.png icon: repo: fontawesome/brands/github name: material palette: - primary: blue + primary: white features: + - navigation.tabs - navigation.instant - navigation.tracking - navigation.expand - navigation.indexes + - navigation.top - toc.integrate edit_uri: edit/master/mkdocs/docs/ @@ -24,3 +34,7 @@ extra: version: default: latest provider: mike + +markdown_extensions: + - toc: + permalink: true