From 4fab4e1d259796e653e8ee08ef0209d85dfff241 Mon Sep 17 00:00:00 2001 From: Thomas Citharel Date: Sun, 17 Nov 2019 18:11:33 +0100 Subject: [PATCH] Move docs to mkdocs and improve them Signed-off-by: Thomas Citharel --- .gitignore | 1 + .gitlab-ci.yml | 2 + docker/tests/Dockerfile | 3 +- .../guides/introduction.md => docs/about.md | 8 +- .../CLI tasks/maintenance_ tasks.md | 52 ++++++++ docs/administration/CLI tasks/manage_users.md | 4 + docs/administration/CLI tasks/relay.md | 25 ++++ docs/administration/dependencies.md | 113 ++++++++++++++++++ .../install => docs/administration}/docker.md | 2 +- .../administration/index.md | 102 +++++++++------- docs/administration/upgrading.md | 91 ++++++++++++++ .../contribute}/code_of_conduct.md | 0 .../contribute}/development.md | 5 +- .../contribute/index.md | 17 +-- .../contribute}/styleguide.md | 3 +- .../development => docs/contribute}/tests.md | 9 +- docs/index.md | 10 ++ docs/logo.png | 1 + docs/theme/partials/footer.html | 107 +++++++++++++++++ mix.exs | 39 ------ mkdocs.yml | 47 ++++++++ support/guides/install/dependencies.md | 53 -------- 22 files changed, 534 insertions(+), 160 deletions(-) rename support/guides/introduction.md => docs/about.md (93%) create mode 100644 docs/administration/CLI tasks/maintenance_ tasks.md create mode 100644 docs/administration/CLI tasks/manage_users.md create mode 100644 docs/administration/CLI tasks/relay.md create mode 100644 docs/administration/dependencies.md rename {support/guides/install => docs/administration}/docker.md (76%) rename support/guides/install/install.md => docs/administration/index.md (54%) create mode 100644 docs/administration/upgrading.md rename {support/guides => docs/contribute}/code_of_conduct.md (100%) rename {support/guides/development => docs/contribute}/development.md (94%) rename support/guides/contributing.md => docs/contribute/index.md (95%) rename {support/guides/development => docs/contribute}/styleguide.md (98%) rename {support/guides/development => docs/contribute}/tests.md (79%) create mode 100644 docs/index.md create mode 120000 docs/logo.png create mode 100644 docs/theme/partials/footer.html create mode 100644 mkdocs.yml delete mode 100644 support/guides/install/dependencies.md diff --git a/.gitignore b/.gitignore index 0a0f0f366..4f7f1202f 100644 --- a/.gitignore +++ b/.gitignore @@ -30,6 +30,7 @@ priv/data/* !priv/data/.gitkeep .vscode/ cover/ +site/ test/fixtures/image_tmp.jpg test/uploads/ uploads/* diff --git a/.gitlab-ci.yml b/.gitlab-ci.yml index 0c47127db..aeff996b4 100644 --- a/.gitlab-ci.yml +++ b/.gitlab-ci.yml @@ -107,6 +107,8 @@ pages: stage: deploy script: - mkdir public + - mkdocs build + - mv site/* public/ - mix deps.get - mix docs - mv doc public/backend diff --git a/docker/tests/Dockerfile b/docker/tests/Dockerfile index 925b8808a..28401e764 100644 --- a/docker/tests/Dockerfile +++ b/docker/tests/Dockerfile @@ -2,9 +2,10 @@ FROM elixir:latest LABEL maintainer="Thomas Citharel " ENV REFRESHED_AT=2019-10-06 -RUN apt-get update -yq && apt-get install -yq build-essential inotify-tools postgresql-client git curl gnupg xvfb libgtk-3-dev libnotify-dev libgconf-2-4 libnss3 libxss1 libasound2 +RUN apt-get update -yq && apt-get install -yq build-essential inotify-tools postgresql-client git curl gnupg xvfb libgtk-3-dev libnotify-dev libgconf-2-4 libnss3 libxss1 libasound2 python3-pip RUN curl -sL https://deb.nodesource.com/setup_10.x | bash && apt-get install nodejs -yq RUN npm install -g yarn wait-on RUN apt-get clean && rm -rf /var/lib/apt/lists/* /tmp/* /var/tmp/* RUN mix local.hex --force && mix local.rebar --force +RUN pip3 install mkdocs mkdocs-material pymdown-extensions pygments mkdocs-git-revision-date-plugin RUN curl http://geolite.maxmind.com/download/geoip/database/GeoLite2-City.tar.gz --output GeoLite2-City.tar.gz -s && tar zxf GeoLite2-City.tar.gz && mkdir -p /usr/share/GeoIP && mv GeoLite2-City_*/GeoLite2-City.mmdb /usr/share/GeoIP/GeoLite2-City.mmdb diff --git a/support/guides/introduction.md b/docs/about.md similarity index 93% rename from support/guides/introduction.md rename to docs/about.md index 576a5f448..bb431dd26 100644 --- a/support/guides/introduction.md +++ b/docs/about.md @@ -1,4 +1,4 @@ -# Mobilizon +# About Mobilizon

@@ -43,7 +43,7 @@ There's no lock-in, you can interact with the event without registration. ## Contributing -We appreciate any contribution to Mobilizon. Check our [Contributing](contributing.html) page for more information. +We appreciate any contribution to Mobilizon. Check our [Contributing](contribute/index.md) page for more information. ## Links @@ -54,11 +54,11 @@ We appreciate any contribution to Mobilizon. Check our [Contributing](contributi ### Discuss * 💬 Matrix: `#Mobilizon:matrix.org` [Riot](https://riot.im/app/#/room/#Mobilizon:matrix.org) - * #️⃣ IRC: `#mobilizon` on Freenode + * IRC: `#mobilizon` on Freenode * 🗣️ Forum: [https://framacolibri.org/c/mobilizon](https://framacolibri.org/c/mobilizon) ### Follow * 🐘 Mastodon: [https://framapiaf.org/@mobilizon](https://framapiaf.org/@mobilizon) * 🐦 Twitter [https://twitter.com/@joinmobilizon](https://twitter.com/@joinmobilizon) -Note: Most federation code comes from [Pleroma](https://pleroma.social), which is `Copyright © 2017-2018 Pleroma Authors - AGPL-3.0` +Note: Most federation code comes from [Pleroma](https://pleroma.social), which is `Copyright © 2017-2019 Pleroma Authors - AGPL-3.0` diff --git a/docs/administration/CLI tasks/maintenance_ tasks.md b/docs/administration/CLI tasks/maintenance_ tasks.md new file mode 100644 index 000000000..4bee7f466 --- /dev/null +++ b/docs/administration/CLI tasks/maintenance_ tasks.md @@ -0,0 +1,52 @@ +# Maintenance tasks + +## Installation + +Generates new configuration files. + +!!! warning + This command generates configuration for your Mobilizon instance and should be run only once when installing. + +If any options are left unspecified, you will be prompted interactively. + +```bash +mix mobilizon.instance gen [] +``` + +### Options +* `-f`, `--force` Whether to erase existing files +* `-o`, `--output PATH` The path to output the `.env` file. Defaults to `.env.production`. +* `--output_psql PATH` The path to output the SQL script. Defaults to `setup_db.psql`. +* `--domain DOMAIN` The instance's domain +* `--instance_name INSTANCE_NAME` The instance's name +* `--admin_email ADMIN_EMAIL` The administrator's email +* `--dbhost HOSTNAME` The database hostname of the PostgreSQL database to use +* `--dbname DBNAME` The name of the database to use +* `--dbuser DBUSER` The database user (aka role) to use for the database connection +* `--dbpass DBPASS` The database user's password to use for the database connection +* `--dbport DBPORT` The database port + +## Depreciated commands + +### move_participant_stats + +Task to move participant stats directly on the `event` table (so there's no need to count event participants each time). +This task should **only be run once** when migrating from `v1.0.0-beta.1` to `v1.0.0-beta.2`. + +This task will be removed in version `v1.0.0-beta.3`. + +```bash +mix mobilizon.move_participant_stats +``` + +### setup_search + +Task to setup search for existing events. + +This task should **only be run once** when migrating from `v1.0.0-beta.1` to `v1.0.0-beta.2`. + +This task will be removed in version `v1.0.0-beta.3`. + +```bash +mix mobilizon.setup_search +``` diff --git a/docs/administration/CLI tasks/manage_users.md b/docs/administration/CLI tasks/manage_users.md new file mode 100644 index 000000000..89bfb8f4e --- /dev/null +++ b/docs/administration/CLI tasks/manage_users.md @@ -0,0 +1,4 @@ +# Manage users + +!!! bug + Not yet existing diff --git a/docs/administration/CLI tasks/relay.md b/docs/administration/CLI tasks/relay.md new file mode 100644 index 000000000..8c63f560c --- /dev/null +++ b/docs/administration/CLI tasks/relay.md @@ -0,0 +1,25 @@ +# Relay + +Manages remote relays + +## Make your instance follow a mobilizon instance + +```bash +mix mobilizon.relay follow +``` + +Example: +```bash +mix mobilizon.relay follow https://example.org/relay +``` + +## Make your instance unfollow a mobilizon instance + +```bash +mix mobilizon.relay unfollow +``` + +Example: +```bash +mix mobilizon.relay unfollow https://example.org/relay +``` diff --git a/docs/administration/dependencies.md b/docs/administration/dependencies.md new file mode 100644 index 000000000..175a966ee --- /dev/null +++ b/docs/administration/dependencies.md @@ -0,0 +1,113 @@ +# Dependencies + +## Debian / Ubuntu and derivatives + +This documentation is appropriate for Debian 10 (Buster) and Ubuntu 18.04 LTS. + +### Security + +We advise to make sure your webserver is secure enough. +For instance you can require authentication through SSH keys and not passwords, install Fail2Ban to block repeated login attempts and block unused ports by installing and configuring a firewall. + +### Basic tools +We begin by making sure some basic tools are installed: + +```bash +sudo apt install curl unzip vim openssl make git +``` + +### Web server +We only officially support nginx. + +```bash +sudo apt install nginx +``` + +### HTTPS Certificates +Then we need to install [certbot](https://certbot.eff.org/), a tool to ask for free Let's Encrypt HTTPS certificates. + +```bash +sudo apt install certbot +``` + +You can use certbot with web server plugins or manually. See [Certbot's documentation](https://certbot.eff.org/instructions). + + +### NodeJS +We install the latest NodeJS version by adding NodeSource repos and installing NodeJS: + +Head over to [this page](https://github.com/nodesource/distributions/blob/master/README.md#table-of-contents) and follow the instructions for `Node.js v12.x`. + +!!! info + Unless stated otherwise, Mobilizon always supports only the latest LTS version of NodeJS. + +!!! tip + NodeSource repos only gives updates for a specific version of NodeJS (it doesn't upgrade itself to a new major version). When a new major version of NodeJS is released, you need to remove the old repo and add the new one. + +### Yarn +Mobilizon uses [Yarn](https://yarnpkg.com/) to manage NodeJS packages, so we need to install it as well. + +Follow the instructions on [this page](https://yarnpkg.com/en/docs/install#debian-stable) to add Yarn's repository and install it. + +!!! info + It is also possible to install `yarn` directly with `npm`: + ```bash + npm install -g yarn + ```. + You need to make sure npm's binary packages folder in your `$PATH` afterwards to use `yarn`. + +### Erlang and Elixir + +The packages from Debian or Ubuntu are badly packaged and often out of date, so we need to add one final source repository. + +Follow the instructions for Ubuntu/Debian on [this page](https://elixir-lang.org/install.html#unix-and-unix-like) to add Erlang Solutions repo and install Erlang and Elixir. + +!!! tip + The Erlang package also wants to install an add-on for Emacs for some reason (but it doesn't install Emacs). If you see a warning, nothing to worry about. + +### PostgreSQL and PostGIS + +Mobilizon uses the [PostgreSQL](https://www.postgresql.org) database, and the PostgreSQL [Postgis](https://postgis.net) extension to store geographical data into PostgreSQL. + +```bash +sudo apt install postgresql postgresql-contrib postgis +``` + +After that we can enable and start the PostgreSQL service. +``` +sudo systemctl --now enable postgresql +``` + +### Misc + +We need the following tools to handle and optimize pictures that are uploaded on Mobilizon. + +```bash +sudo apt install imagemagick +``` + +The following packages are optional, Mobilizon can run without them. + +```bash +sudo apt install webp gifsicle jpegoptim optipng pngquant +``` + +Once finished, let's [head back to the install guide](index.md). + +## Arch Linux + +Run the following command to install all at once: +```bash +sudo pacman -S nodejs postgresql openssl git wget unzip base-devel yarn nginx elixir postgis imagemagick +``` + +Now that dependencies are installed, before running Mobilizon you should start PostgreSQL: +``` +sudo systemctl --now enable postgresql +``` + +Once finished, let's [head back to the install guide](index.md). + +## Other distributions + +Feel free to update this file in a pull request! diff --git a/support/guides/install/docker.md b/docs/administration/docker.md similarity index 76% rename from support/guides/install/docker.md rename to docs/administration/docker.md index 790d3a9e7..421ac3af0 100644 --- a/support/guides/install/docker.md +++ b/docs/administration/docker.md @@ -12,4 +12,4 @@ Then, just run `make` to build containers. make ``` -This will start a database container, an API container and the front-end container running on localhost. +This will start a database container, an API container also containing the front-end running on `localhost`. diff --git a/support/guides/install/install.md b/docs/administration/index.md similarity index 54% rename from support/guides/install/install.md rename to docs/administration/index.md index a4da4d074..6c606e822 100644 --- a/support/guides/install/install.md +++ b/docs/administration/index.md @@ -1,50 +1,50 @@ # Install +## Pre-requisites + +* A Linux machine with **root access** +* A **domain name** (or subdomain) for the Mobilizon server, e.g. `example.net` +* An **SMTP server** to deliver emails + +!!! tip + You can also install Mobilizon [with Docker](docker.md). + ## Dependencies -Follow the steps of the [dependencies guide](dependencies.html) +Mobilizon requires Elixir, NodeJS and PostgreSQL among other things. -## Database +Installing dependencies depends on the system you're using. Follow the steps of the [dependencies guide](dependencies.md). -Create the production database and a mobilizon user inside PostgreSQL: +## Setup -```bash -sudo -u postgres createuser -P mobilizon -sudo -u postgres createdb -O mobilizon mobilizon_prod -``` - -Then enable extensions Mobilizon needs: - -```bash -sudo -u postgres psql -c "CREATE EXTENSION postgis;" mobilizon_prod -sudo -u postgres psql -c "CREATE EXTENSION pg_trgm;" mobilizon_prod -sudo -u postgres psql -c "CREATE EXTENSION unaccent;" mobilizon_prod -``` - - -## Mobilizon user - -Create a `mobilizon` user with `/home/mobilizon` home: +We're going to use a dedicated `mobilizon` user with `/home/mobilizon` home: ```bash sudo adduser --disabled-login mobilizon +``` + +!!! tip + + On FreeBSD + + ``` bash + sudo pw useradd -n mobilizon -d /home/mobilizon -s /usr/local/bin/bash -m + sudo passwd mobilizon + ``` + +Then let's connect as this user: + +```bash sudo -i -u mobilizon ``` -**On FreeBSD** +Let's start by cloning the repository in a directory named `live`: -```bash -sudo pw useradd -n mobilizon -d /home/mobilizon -s /usr/local/bin/bash -m -sudo passwd mobilizon -``` - -You can now fetch the code with git: ```bash git clone https://framagit.org/framasoft/mobilizon live && cd live ``` -## Configuration -### Backend +## Installing dependencies Install Elixir dependencies @@ -52,23 +52,12 @@ Install Elixir dependencies mix deps.get ``` -Configure your instance with +Then compile these dependencies and Mobilizon (this can take a few minutes) ```bash -mix mobilizon.instance gen +mix compile ``` -This will ask you questions about your instance and generate a `.env.prod` file. - -### Migration - -Run database migrations: `mix ecto.migrate`. You will have to do this again after most updates. - -> If some migrations fail, it probably means you're not using a recent enough version of PostgreSQL, -or that you haven't installed [the required extensions](#database). - -### Front-end - Go into the `js/` directory ```bash @@ -81,11 +70,34 @@ and install the Javascript dependencies yarn install ``` -Finally, build the front-end with +Finally, we can build the front-end (this can take a few seconds) ```bash yarn run build ``` +Let's go back to the main directory +```bash +cd ../ +``` + +## Configuration + +Mobilizon provides a command line tool to generate configuration + +```bash +mix mobilizon.instance gen +``` + +This will ask you questions about your instance and generate a `.env.prod` file. + + +### Migration + +Run database migrations: `mix ecto.migrate`. You will have to do this again after most updates. + +!!! tip + If some migrations fail, it probably means you're not using a recent enough version of PostgreSQL, or that you haven't installed the required extensions. + ## Services ### Systemd @@ -114,7 +126,7 @@ It will run Mobilizon and enable startup on boot. You can follow the logs with sudo journalctl -fu mobilizon.service ``` -The Elixir server runs on port 4000 on the local interface only, so you need to add a reverse-proxy. +The Mobilizon server runs on port 4000 on the local interface only, so you need to add a reverse-proxy. ## Reverse proxy @@ -134,4 +146,4 @@ sudo ln -s /etc/nginx/sites-available/mobilizon.conf /etc/nginx/sites-enabled/ Edit the file `/etc/nginx/sites-available` and adapt it to your own configuration. -Test the configuration with `sudo nginx -t` and reload nginx with `systemctl reload nginx`. \ No newline at end of file +Test the configuration with `sudo nginx -t` and reload nginx with `systemctl reload nginx`. diff --git a/docs/administration/upgrading.md b/docs/administration/upgrading.md new file mode 100644 index 000000000..bf20d45e1 --- /dev/null +++ b/docs/administration/upgrading.md @@ -0,0 +1,91 @@ +--- +title: Upgrading to a new release +--- + +# Preparing + +The release page contains a changelog, and below it, upgrade instructions. **Read and understand** the release instructions. + +Some tasks (like database migrations) can take a while, so we advise you to run commands inside a `tmux` or `screen`. + +# Backup + +Always make sure your database and `.env.production` file are properly backuped before performing upgrades. + +Unless stated otherwise in the release notes, the following steps are enough to upgrade Mobilizon. + +# Steps + +### Fetch latest code +Switch to the `mobilizon` user: + +```bash +sudo -i -u mobilizon +``` + +And navigate to the Mobilizon root directory: + +```bash +cd /home/mobilizon/live +``` + +Fetch the latest tags +```bash +git fetch --tags +``` + +And checkout the tag you want to switch to. For instance, if I want to upgrade to version `v1.1`: +```bash +git checkout v1.1 +``` + +### Fetch new dependencies +Fetch new and/or updated Elixir and NodeJS dependencies +```bash +mix deps.get +``` +```bash +cd js +yarn install +``` + +### Rebuild Mobilizon's front-end +```bash +yarn run build +cd ../ +``` + +### Recompile Mobilizon +```bash +mix compile +``` +Let's switch back to your regular user. + +### Stop running Mobilizon processes +```bash +sudo systemctl stop mobilizon +``` + +### Perform database migrations + +Go back to the `mobilizon` user. +```bash +sudo -i -u mobilizon +cd live +mix ecto.migrate +``` +### Restart Mobilizon +Let's switch back one last time to your regular user. +```bash +sudo systemctl restart mobilizon +``` + +You can follow the Mobilizon logs to check that everything works properly. +```bash +sudo journalctl -u mobilizon -f +``` + +**That’s all!** You’re running the new version of Mobilizon now. + +If you have issues after upgrading, try reviewing upgrade steps and release notes. +Then feel free to [contact us](../about.md#discuss) or file an issue on [our Gitlab](https://framagit.org/framasoft/mobilizon/issues) diff --git a/support/guides/code_of_conduct.md b/docs/contribute/code_of_conduct.md similarity index 100% rename from support/guides/code_of_conduct.md rename to docs/contribute/code_of_conduct.md diff --git a/support/guides/development/development.md b/docs/contribute/development.md similarity index 94% rename from support/guides/development/development.md rename to docs/contribute/development.md index e22a860c4..a72b7d5cb 100644 --- a/support/guides/development/development.md +++ b/docs/contribute/development.md @@ -10,6 +10,7 @@ git clone git@framagit.org:framasoft/mobilizon.git && cd mobilizon ``` Run Mobilizon: + * with Docker and Docker-Compose (**Recommended**) * without Docker and Docker-Compose (This involves more work on your part, use Docker and Docker-Compose if you can) @@ -25,7 +26,7 @@ Run Mobilizon: * Install dependencies: * Elixir (and Erlang) by following the instructions at [https://elixir-lang.github.io/install.html](https://elixir-lang.github.io/install.html) * [PostgreSQL]() with PostGIS - * Install NodeJS (we guarantee support for the latest LTS and later) ![](https://img.shields.io/badge/node-%3E%3D%2010.0+-brightgreen.svg) + * Install NodeJS (we guarantee support for the latest LTS and later) ![](https://img.shields.io/badge/node-%3E%3D%2012.0+-brightgreen.svg) * Start services: * Start postgres * Setup services: @@ -46,4 +47,4 @@ Run Mobilizon: * Start Phoenix endpoint with `mix phx.server`. The client development server will also automatically be launched and will reload on file change. Now you can visit [`localhost:4000`](http://localhost:4000) in your browser -and see the website (server *and* client) in action. \ No newline at end of file +and see the website (server *and* client) in action. diff --git a/support/guides/contributing.md b/docs/contribute/index.md similarity index 95% rename from support/guides/contributing.md rename to docs/contribute/index.md index 264cb4820..f0013d9dc 100644 --- a/support/guides/contributing.md +++ b/docs/contribute/index.md @@ -40,17 +40,11 @@ This project is part of [Framasoft](https://framasoft.org)'s [Contributopia Camp ![Framameet illustration on Contributopia Website](https://contributopia.org/img/services-framameet.jpg) -### We practice [Ethical Design](https://2017.ind.ie/ethical-design/) - -We endeavour to build technology that respects human rights, human effort, and human experience, and hope you will join in this effort. - -[![Ethical Design diagram](https://i.imgur.com/O7RJo60.png)](https://2017.ind.ie/ethical-design/) - --- -## [Code Of Conduct](code_of_conduct.html) +## [Code Of Conduct](code_of_conduct.md) -We require all participants to read and accept our [Code of Conduct](code_of_conduct.html). +We require all participants to read and accept our [Code of Conduct](code_of_conduct.md). --- @@ -70,7 +64,8 @@ Please go through the checklist below before posting any ✨ 💄 🐛 * **Perform a cursory search** in the issue tracker to see if the enhancement has already been suggested. If it has, add a comment to the existing issue instead of opening a new one. * Never report security related issues, vulnerabilities or bugs including sensitive information to the issue tracker, or elsewhere in public. Instead, sensitive bugs must be sent by email to tcit plus mobilizon at framasoft dot org. -> **Note:** If you find a **Closed** issue that seems like it is the same thing that you're experiencing, open a new issue and include a link to the original issue in the body of your new one. +!!! note + If you find a **Closed** issue that seems like it is the same thing that you're experiencing, open a new issue and include a link to the original issue in the body of your new one. ### Suggesting Features & Enhancements @@ -167,7 +162,7 @@ Unsure where to begin contributing? You can start by looking through issues tagg #### Local development -Mobilizon can be developed locally. For instructions on how to do this, please see [the documentation](development.html). +Mobilizon can be developed locally. For instructions on how to do this, please see [the documentation](development.md). #### Coding & git practices @@ -192,7 +187,7 @@ Mobilizon can be developed locally. For instructions on how to do this, please s #### Merge requests -* Follow [the code styleguides](styleguide.html). +* Follow [the code styleguides](styleguide.md). * Document new code based on [the documentation styleguide](https://hexdocs.pm/elixir/writing-documentation.html). * Each merge request should implement ONE feature or bugfix. If you want to add or fix more than one thing, submit more than one merge request. * Fill in the merge request template below. diff --git a/support/guides/development/styleguide.md b/docs/contribute/styleguide.md similarity index 98% rename from support/guides/development/styleguide.md rename to docs/contribute/styleguide.md index 7965df7b9..9a70cc48f 100644 --- a/support/guides/development/styleguide.md +++ b/docs/contribute/styleguide.md @@ -5,6 +5,7 @@ We format our code with the Elixir Formatter and check for issues with [Credo](https://github.com/rrrene/credo) (a few rules are not blocking). Please run these two commands before pushing code: + * `mix format` * `mix credo` @@ -25,4 +26,4 @@ We also try to follow the [official Vue.js style guide](https://vuejs.org/v2/sty ### Styleguide -We present the components used on Mobilizon's front-end here: https://framasoft.frama.io/mobilizon/frontend/. The documentation is builded through [Vue Styleguidist](https://vue-styleguidist.github.io/) \ No newline at end of file +We present the components used on Mobilizon's front-end here: https://framasoft.frama.io/mobilizon/frontend/. The documentation is builded through [Vue Styleguidist](https://vue-styleguidist.github.io/) diff --git a/support/guides/development/tests.md b/docs/contribute/tests.md similarity index 79% rename from support/guides/development/tests.md rename to docs/contribute/tests.md index bb46b2f97..c872ecc79 100644 --- a/support/guides/development/tests.md +++ b/docs/contribute/tests.md @@ -9,7 +9,8 @@ To launch all the tests: mix test ``` -> If you're using Docker, you can use `make test` +!!! info + If you're using Docker, you can use `make test` If you want test coverage: @@ -31,7 +32,8 @@ If you want to test a specific test, block or line: mix test test/mobilizon/actors/actors_test.exs:85 ``` -> Note: The coveralls.html also works the same +!!! tip + Note: The `coveralls.html` also works the same ## Front-end @@ -58,4 +60,5 @@ npx cypress open ``` to open the interactive GUI. -Cypress provided [a subscription](https://www.cypress.io/oss-plan) to their recording dashboard since Mobilizon is an Open-Source project. Thanks! \ No newline at end of file +!!! info + Cypress provided [a subscription](https://www.cypress.io/oss-plan) to their recording dashboard since Mobilizon is an Open-Source project. Thanks! diff --git a/docs/index.md b/docs/index.md new file mode 100644 index 000000000..2f5fb4e48 --- /dev/null +++ b/docs/index.md @@ -0,0 +1,10 @@ +--- +title: Mobilizon documentation +--- + +Welcome to the Mobilizon documentation + +* [Learn more about Mobilizon](about.md) +* Learn how to use Mobilizon (not yet written) +* [Learn how to install Mobilizon](administration/index.md) +* [Learn how to contribute to Mobilizon](contribute/index.md) diff --git a/docs/logo.png b/docs/logo.png new file mode 120000 index 000000000..09e73d859 --- /dev/null +++ b/docs/logo.png @@ -0,0 +1 @@ +../js/public/img/mobilizon_logo.png \ No newline at end of file diff --git a/docs/theme/partials/footer.html b/docs/theme/partials/footer.html new file mode 100644 index 000000000..d4b658aa3 --- /dev/null +++ b/docs/theme/partials/footer.html @@ -0,0 +1,107 @@ + + +{% import "partials/language.html" as lang with context %} + + +

diff --git a/mix.exs b/mix.exs index 345625736..f53064471 100644 --- a/mix.exs +++ b/mix.exs @@ -156,12 +156,7 @@ defmodule Mobilizon.Mixfile do defp docs() do [ source_ref: "v#{@version}", - extra_section: "GUIDES", - main: "introduction", - api_reference: false, groups_for_modules: groups_for_modules(), - extras: extras(), - groups_for_extras: groups_for_extras(), nest_modules_by_prefix: [ Mobilizon, MobilizonWeb, @@ -173,20 +168,6 @@ defmodule Mobilizon.Mixfile do ] end - defp extras() do - [ - "support/guides/development/development.md", - "support/guides/development/tests.md", - "support/guides/development/styleguide.md", - "support/guides/install/install.md", - "support/guides/install/dependencies.md", - "support/guides/install/docker.md", - "support/guides/introduction.md", - "support/guides/contributing.md", - "support/guides/code_of_conduct.md" - ] - end - defp groups_for_modules() do [ Models: [ @@ -326,24 +307,4 @@ defmodule Mobilizon.Mixfile do ] ] end - - defp groups_for_extras() do - [ - Introduction: [ - "support/guides/introduction.md", - "support/guides/contributing.md", - "support/guides/code_of_conduct.md" - ], - Development: [ - "support/guides/development/development.md", - "support/guides/development/tests.md", - "support/guides/development/styleguide.md" - ], - Production: [ - "support/guides/install/install.md", - "support/guides/install/docker.md", - "support/guides/install/dependencies.md" - ] - ] - end end diff --git a/mkdocs.yml b/mkdocs.yml new file mode 100644 index 000000000..c3870a524 --- /dev/null +++ b/mkdocs.yml @@ -0,0 +1,47 @@ +site_name: Mobilizon +repo_name: 'framasoft/mobilizon' +repo_url: 'https://framagit.org/framasoft/mobilizon' +extra: + repo_icon: gitlab + social: + - type: 'twitter' + link: 'https://twitter.com/joinmobilizon' +markdown_extensions: + - admonition + - codehilite + - footnotes + - meta + - toc: + permalink: true + - pymdownx.superfences + - pymdownx.magiclink + - pymdownx.smartsymbols + - pymdownx.tilde + - pymdownx.mark +plugins: + - search + - git-revision-date +theme: + name: 'material' + custom_dir: 'docs/theme/' + palette: + primary: 'yellow' + accent: 'deep purple' + font: false + #logo: 'logo.png' + logo: + icon: 'calendar_today' + feature: + tabs: true +# +#nav: +# - Home: 'index.md' +# - About: 'about.md' +# - Administration: +# - Install: 'administration/install.md' +# - Dependencies: 'administration/dependencies.md' +# - Docker: 'administration/docker.md' +# - Contribute: +# - Contribute: 'contribute.md' +# - Development: 'contribute/development.md' +# - Styleguide: diff --git a/support/guides/install/dependencies.md b/support/guides/install/dependencies.md deleted file mode 100644 index b8c111bec..000000000 --- a/support/guides/install/dependencies.md +++ /dev/null @@ -1,53 +0,0 @@ -# Dependencies - - -- [Debian / Ubuntu and derivatives](#debian--ubuntu-and-derivatives) -- [Arch Linux](#arch-linux) -- [Other distributions](#other-distributions) - -## Debian / Ubuntu and derivatives - 1. On a fresh Debian/Ubuntu, as root user, install basic utility programs needed for the installation - -``` -sudo apt install curl unzip vim -``` - - 2. It would be wise to disable root access and to continue this tutorial with a user with sudoers group access - 3. Install certbot (choose instructions for nginx and your distribution): - [https://certbot.eff.org/all-instructions](https://certbot.eff.org/all-instructions) - 4. Install NodeJS 10.x (current LTS): - [https://nodejs.org/en/download/package-manager/#debian-and-ubuntu-based-linux-distributions](https://nodejs.org/en/download/package-manager/#debian-and-ubuntu-based-linux-distributions) - 5. Install yarn, and be sure to have [a recent version](https://github.com/yarnpkg/yarn/releases/latest): - [https://yarnpkg.com/en/docs/install#linux-tab](https://yarnpkg.com/en/docs/install#linux-tab) - 6. Install Erlang and Elixir: - [https://elixir-lang.org/install.html#unix-and-unix-like](https://elixir-lang.org/install.html#unix-and-unix-like) - 7. Install PostGIS: - [https://postgis.net/install/](https://postgis.net/install/) - 8. Run: - -``` -sudo apt update -sudo apt install nginx postgresql postgresql-contrib openssl make git esl-erlang elixir postgis imagemagick -``` - -Now that dependencies are installed, before running Mobilizon you should start PostgreSQL: -``` -sudo systemctl start postgresql -``` - -## Arch Linux - - 1. Run: - -``` -sudo pacman -S nodejs postgresql openssl git wget unzip base-devel yarn nginx elixir postgis imagemagick -``` - -Now that dependencies are installed, before running Mobilizon you should start PostgreSQL and Redis: -``` -sudo systemctl start postgresql -``` - -## Other distributions - -Feel free to update this file in a pull request!