Merge branch 'cli-docs' into 'master'

Cli docs

See merge request funkwhale/funkwhale!863

.gitlab-ci.yml

@@ -20,91 +20,73 @@ review_front:
   image: node:11
   when: manual
   allow_failure: true
+  variables:
+    BASE_URL: /-/$CI_PROJECT_NAME/-/jobs/$CI_JOB_ID/artifacts/front-review/
+    VUE_APP_ROUTER_BASE_URL: /-/$CI_PROJECT_NAME/-/jobs/$CI_JOB_ID/artifacts/front-review/
+    VUE_APP_INSTANCE_URL: $REVIEW_INSTANCE_URL
   before_script:
     - curl -L -o /usr/local/bin/jq https://github.com/stedolan/jq/releases/download/jq-1.5/jq-linux64
     - chmod +x /usr/local/bin/jq
+    - rm -rf front-review
+    - mkdir front-review
     - cd front
   script:
     - yarn install
     - yarn run i18n-compile
     # this is to ensure we don't have any errors in the output,
     # cf https://dev.funkwhale.audio/funkwhale/funkwhale/issues/169
-    - VUE_APP_INSTANCE_URL=$REVIEW_INSTANCE_URL yarn run build | tee /dev/stderr | (! grep -i 'ERROR in')
+    - yarn run build | tee /dev/stderr | (! grep -i 'ERROR in')
-    - mkdir -p /static/front/$CI_PROJECT_PATH_SLUG-$CI_BUILD_REF_SLUG
+    - cp -r dist/* ../front-review
-    - cp -r dist/* /static/front/$CI_PROJECT_PATH_SLUG-$CI_BUILD_REF_SLUG
+  artifacts:
+    expire_in: 2 weeks
+    paths:
+      - front-review
   cache:
     key: "funkwhale__front_dependencies"
     paths:
       - front/node_modules
       - front/yarn.lock
-  environment:
-    name: review/front/$CI_PROJECT_PATH_SLUG-$CI_BUILD_REF_SLUG
-    url: http://front-$CI_PROJECT_PATH_SLUG-$CI_BUILD_REF_SLUG.$REVIEW_DOMAIN
-    on_stop: stop_front_review
   only:
     - branches
   tags:
-    - funkwhale-review
+    - docker
+  environment:
+    name: review/front/$CI_COMMIT_REF_NAME
+    url: http://$CI_PROJECT_NAMESPACE.pages.funkwhale.audio/-/$CI_PROJECT_NAME/-/jobs/$CI_JOB_ID/artifacts/front-review/index.html
 
-stop_front_review:
-  stage: review
-  script:
-    - rm -rf /static/front/$CI_PROJECT_PATH_SLUG-$CI_BUILD_REF_SLUG/
-  variables:
-    GIT_STRATEGY: none
-  when: manual
-  only:
-    - branches
-  environment:
-    name: review/front/$CI_PROJECT_PATH_SLUG-$CI_BUILD_REF_SLUG
-    action: stop
-  tags:
-    - funkwhale-review
 
 review_docs:
   stage: review
-  image: python:3.6
   when: manual
   allow_failure: true
+  image: python:3.6
   variables:
-    BUILD_PATH: "../public"
+    BUILD_PATH: "../docs-review"
   before_script:
+    - rm -rf docs-review
+    - mkdir docs-review
     - cd docs
     - apt-get update
     - apt-get install -y graphviz
     - pip install sphinx
-
+  script:
+    - ./build_docs.sh
   cache:
     key: "$CI_PROJECT_ID__sphinx"
     paths:
       - "$PIP_CACHE_DIR"
-  script:
+  artifacts:
-    - ./build_docs.sh
+    expire_in: 2 weeks
-    - mkdir -p /static/docs/$CI_PROJECT_PATH_SLUG-$CI_BUILD_REF_SLUG
+    paths:
-    - cp -r $CI_PROJECT_DIR/public/* /static/docs/$CI_PROJECT_PATH_SLUG-$CI_BUILD_REF_SLUG
+      - docs-review
-  environment:
-    name: review/docs/$CI_PROJECT_PATH_SLUG-$CI_BUILD_REF_SLUG
-    url: http://docs-$CI_PROJECT_PATH_SLUG-$CI_BUILD_REF_SLUG.$REVIEW_DOMAIN
-    on_stop: stop_docs_review
   only:
     - branches
   tags:
-    - funkwhale-review
+    - docker
+  environment:
+    name: review/docs/$CI_COMMIT_REF_NAME
+    url: http://$CI_PROJECT_NAMESPACE.pages.funkwhale.audio/-/$CI_PROJECT_NAME/-/jobs/$CI_JOB_ID/artifacts/docs-review/index.html
 
-stop_docs_review:
-  stage: review
-  script:
-    - rm -rf /static/docs/$CI_PROJECT_PATH_SLUG-$CI_BUILD_REF_SLUG/
-  variables:
-    GIT_STRATEGY: none
-  when: manual
-  only:
-    - branches
-  environment:
-    name: review/docs/$CI_PROJECT_PATH_SLUG-$CI_BUILD_REF_SLUG
-    action: stop
-  tags:
-    - funkwhale-review
 
 black:
   image: python:3.6

docs/cli/examples.rst

@@ -0,0 +1,64 @@
+Funkwhale CLI examples
+======================
+
+Uploading local files
+---------------------
+
+**Goal**: create a library and upload all MP3 files from ``~/Music`` to it
+
+**Commands**::
+
+    funkwhale libraries create --name "My awesome library" --visibility me
+    # copy the returned UUID
+    funkwhale uploads create <UUID> ~/Music/**/*.mp3
+
+
+Favorite an entire album
+------------------------
+
+**Goal**: retrieve all the tracks from an album and add these to your favorites
+
+**Commands**::
+
+    # retrieve the album ID
+    funkwhale albums ls "The Slip"
+
+    # Copy the ID, then retrieve 100 pages of tracks from that album
+    # get only the IDs and pipe those to the favorite creation command
+    funkwhale tracks ls -f "album=<ID>" --ids --limit 100 \
+        | xargs funkwhale favorites tracks create
+
+
+Mirror an artist discography locally
+------------------------------------
+
+**Goal**: Download the discography of an artist locally, in the ``~/Music`` directory, in an ``Artist/Album/Track`` folder hierarchy
+
+**Commands**::
+
+    # retrieve the artist ID
+    funkwhale artists ls "Nine Inch Nails"
+
+    # Copy the ID, then retrieve 100 pages of tracks from that artist
+    # get only the IDs and pipe those to the download command
+    funkwhale tracks ls -f "artist=<ID>" --ids --limit 100 \
+        | xargs funkwhale tracks download \
+            -f mp3 -d ~/Music -t "{artist}/{album}/{title}.{extension}"
+
+
+Open a remote album in VLC
+--------------------------
+
+**Goal**: Variation of the previous example, but instead of downloading an artist discography, we listen to an album in VLC
+
+**Commands**::
+
+    # retrieve the album ID
+    funkwhale albums ls "The Slip"
+
+    # Copy the ID, then retrieve 100 pages of tracks from that album
+    # get only the IDs, download the corresponding tracks and pipe the audio
+    # directly to VLC
+    funkwhale tracks ls -f "album=<ID>" --ids --limit 100 \
+        | xargs funkwhale tracks download \
+        | vlc -

docs/cli/index.rst

@@ -0,0 +1,252 @@
+Funkwhale CLI
+=============
+
+`Funkwhale CLI <https://dev.funkwhale.audio/funkwhale/cli/>`_ is a command-line interface you can install on your local computer
+to interact with any Funkwhale server via the REST API. It's especially useful if you need to do repetitive operations
+or write scripts that interact with Funkwhale servers.
+
+Here is a (non-exhaustive) list of operations you can perform via the CLI:
+
+- Manage libraries
+- Upload local files
+- Retrieve and search tracks, albums and artists
+- Download tracks
+- Manage playlists
+- Manage favorites
+
+.. contents:: Table of Contents
+
+
+
+Installation
+------------
+
+We provide a prebuilt binary for Linux::
+
+    curl -L "https://dev.funkwhale.audio/funkwhale/cli/-/jobs/artifacts/master/raw/funkwhale?job=build-linux" -o /usr/local/bin/funkwhale
+    chmod +x /usr/local/bin/funkwhale
+
+You can also install from source with::
+
+    pip3 install --user git+https://dev.funkwhale.audio/funkwhale/cli
+    # the executable will be available at ~/.local/bin/funkwhale
+
+.. note::
+
+    Installing from source requires you have Python 3.6 or higher available.
+
+You can check the installation was successful by running ``funkwhale --help``. This should output
+the list of available commands and the CLI description.
+
+Basic usage
+-----------
+
+Here are a couple of commands you can try to get started:
+
+.. code-block:: shell
+
+    # Display public server info of demo.funkwhale.audio
+    funkwhale -H https://demo.funkwhale.audio server info
+
+    # List tracks from open.audio
+    funkwhale -H https://open.audio tracks ls
+
+    # Search artists matching "zebra" on open.audio
+    funkwhale -H https://open.audio artists ls "zebra"
+
+More examples
+-------------
+
+You should find enough in this reference document to start using the CLI on your own.
+
+However, we've compiled :doc:`a list of example uses of the CLI <examples>` with advice and explanations, if you want to check it out ;)
+
+Getting help
+------------
+
+The most basic way to get help is to run ``funkwhale --help``. It will list available commands, namespaces and arguments that are common to all commands.
+
+You can also append the ``--help`` flag after any command to get more information about its arguments and options, like this: ``funkwhale albums ls --help``
+
+The CLI offers nested commands. For instance, ``funkwhale albums`` isn't a valid command in itself, but a namespace for all albums-related commands.
+
+To get the help of a specific namespace and list all its available commands, simply run ``funkwhale <namespace> --help``.
+
+Authentication
+--------------
+
+The CLI uses JWT tokens to interact with the API. You can either:
+
+1. Run ``funkwhale login``, which will ask you your Funkwhale username and password and store a JWT token in your local keyring. This token will be used automatically afterwards.
+2. Explicitly pass a token to the command via the ``-t`` flag or the ``FUNKWHALE_TOKEN`` environment variable
+
+If you use ``funkwhale login``, you can delete the local token with ``funkwhale logout``.
+
+You can check that you are fully authenticated by running ``funkwhale users me``. It will display information relating to your user profile.
+
+Configuration
+-------------
+
+To work, the CLI needs to be pointed to a Funkwhale server. This can be done in various ways:
+
+- Via the ``-H https://funkwhale.domain`` flag when calling the CLI
+- Via the ``FUNKWHALE_SERVER_URL`` environment variable
+- Via an env file (see below)
+
+Env file
+^^^^^^^^
+
+The CLI will try to read configuration options from a ``.env`` file in the current directory, or from ``~/.config/funkwhale/env``.
+
+You can also give it a path to another env file via the ``-e /path/to/.envfile`` flag or the ``ENV_FILE`` environment variable.
+
+An env file simply contains a list of variables, using the same syntax as environment variables (comments starting with # are allowed). Example::
+
+    # ~/Music/.env
+    FUNKWHALE_SERVER_URL=https://my.funkwhale.server
+
+
+List of configuration options
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
++--------------------------------------+------------------------------------------------+--------------------------------------------+---------------------------------------------------------------+
+| CLI Flag                             | Environment variable                           | Example value                              | Description                                                   |
++--------------------------------------+------------------------------------------------+--------------------------------------------+---------------------------------------------------------------+
+| ``-e``, ``--env-file``               | ``ENV_FILE``                                   | ``~/Music/.env``                           | Path to a local env file to use for configuration             |
++--------------------------------------+------------------------------------------------+--------------------------------------------+---------------------------------------------------------------+
+| ``-H``, ``--url``                    | ``FUNKWHALE_SERVER_URL``                       | ``https://demo.funkwhale.audio``           | The URL of the Funkwhale server the CLI should contact        |
++--------------------------------------+------------------------------------------------+--------------------------------------------+---------------------------------------------------------------+
+| ``-t``, ``--token``                  | ``FUNKWHALE_TOKEN``                            | ``eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI``        | A JWT token to use for authentication                         |
++--------------------------------------+------------------------------------------------+--------------------------------------------+---------------------------------------------------------------+
+| ``--no-login``                       | ``FUNKWHALE_NO_LOGIN``                         | ``true``                                   | Completely disable authentication and keyring                 |
++--------------------------------------+------------------------------------------------+--------------------------------------------+---------------------------------------------------------------+
+| ``-v``, ``--verbosity``              |                                                | One of ``CRITICAL``, ``ERROR``,            | Control the verbosity (default is INFO)                       |
+|                                      |                                                | ``WARNING``, ``INFO`` or ``DEBUG``         |                                                               |
++--------------------------------------+------------------------------------------------+--------------------------------------------+---------------------------------------------------------------+
+| ``-q``, ``--quiet``                  | ``FUNKWHALE_QUIET``                            | ``true``                                   | Completely disable logging                                    |
++--------------------------------------+------------------------------------------------+--------------------------------------------+---------------------------------------------------------------+
+
+Listing results
+---------------
+
+All commands that list results - such as ``funkwhale albums ls`` or ``funkwhale tracks ls`` - share similar behaviors and sets of arguments.
+
+Filtering
+^^^^^^^^^
+
+Results can be filtered using the ``-f`` or ``--filter`` flag. Provided values are transmitted directly in the querystring when the requests to the API is made::
+
+    # retrieve playable tracks
+    funkwhale tracks ls -f "playable=true"
+
+The flag can be provided multiple times, to add multiple filter conditions::
+
+    # retrieve playable tracks with a CC-BY-SA 4.0 license
+    funkwhale tracks ls -f "playable=true" -f "license=cc-by-sa-4.0"
+
+.. note::
+
+    The list of supported fields for filtering depends on the resource being queried, and can be found in our `API documentation`_.
+
+
+Searching
+^^^^^^^^^
+
+Any text provided after the ``ls`` command will be considered a search query and transmitted to the API::
+
+    # retrieve tracks matching the search query "Electro Swing"
+    funkwhale tracks ls Electro Swing
+
+.. note::
+
+    This is technically equivalent to filtering with a ``q`` parameter as described above::
+
+        funkwhale tracks ls -f "q=Electro Swing"
+
+
+Ordering
+^^^^^^^^
+
+You can control the ordering of the results with the `-o` or ``--ordering`` flag::
+
+    # retrieve albums by creation date, in ascending order
+    funkwhale albums ls -o creation_date
+
+.. note::
+
+    Ordering in descending order is supported by prefixing the field name with ``-``, e.g: ``-o -creation_date``
+
+.. note::
+
+    The list of supported fields for ordering depends on the resource being queried, and can be found in our `API documentation`_.
+
+
+Pagination
+^^^^^^^^^^
+
+You can retrieve a specific result page using the ``-p`` or ``--page`` flag::
+
+    # retrieve the second page of albums
+    funkwhale albums ls -p 2
+
+You can also alter the size of the pages using the ``-s`` or ``--page-size`` flag::
+
+    # retrieve five albums
+    funkwhale albums ls -s 5
+
+Sometimes, you may want to retrieve multiple pages of results at once. This is supported using the ``-l`` or ``--limit`` flag::
+
+    # retrieve the first 3 pages of albums
+    funkwhale albums ls -l 3
+
+You can, of course, combine these flags::
+
+    # retrieve 3 pages of 12 albums, starting on the 4th page
+    funkwhale albums ls --limit 3 --page-size 12 --page 4
+
+Output
+^^^^^^
+
+While the default output displays a human-readable table, you can customize it.
+
+The ``--raw`` flag will simply output the raw JSON payload returned by the API server::
+
+    funkwhale artists ls --raw
+
+The ``-h`` or ``--no-headers`` flag simply removes the table column headers.
+
+The ``-t`` or ``--format`` flag alters the rendering of result, depending on the provided value::
+
+    # list artists outputting a html table
+    funkwhale artists ls -t html
+    # output a github/markdown table
+    funkwhale artists ls -t github
+
+Available formats are: ``fancy_grid``, ``github``, ``grid``, ``html``, ``jira``, ``latex``, ``latex_booktabs``, ``latex_raw``, ``mediawiki``, ``moinmoin``, ``orgtbl``, ``pipe``, ``plain``, ``presto``, ``psql``, ``rst``, ``simple``, ``textile``, ``tsv``, ``youtrack``
+
+The ``-c`` or ``--column`` flag gives you control on the displayed columns::
+
+    # list artists, displaying only artist ID and number of tracks
+    funkwhale artists ls -c ID -c Tracks
+
+For a given resource, the list of available columns can be found by running ``funkwhale <resource> ls --help``.
+
+The ``-i`` or ``--ids`` flag displays only the IDs of results, one per line::
+
+    funkwhale artists ls --ids
+
+This is especially useful in conjunction with other commands (like deletion commands) and piping.
+Note that this is also technically equivalent to applying the ``--no-headers``, ``--format plain`` and ``--column ID`` flags.
+
+Deleting objects
+----------------
+
+Some resources support deletion, via commands such as ``funkwhale libraries rm`` or ``funkwhale playlists rm``, followed by one or more IDs::
+
+    # delete playlists 42 and 23
+    funkwhale playlists rm 42 23
+
+By default, the ``rm`` command will ask for confirmation, but you can disable this behavior by providing the ``--no-input`` flag.
+
+
+.. _API Documentation: https://docs.funkwhale.audio/swagger/

docs/users/index.rst

@@ -28,6 +28,7 @@ Using Funkwhale
    radios
    follow
    apps
+   ../cli/index
 
 Troubleshooting Issues
 ----------------------

front/src/router/index.js

@@ -3,9 +3,11 @@ import Router from 'vue-router'
 
 Vue.use(Router)
 
+console.log('PROCESS', process.env)
 export default new Router({
   mode: 'history',
   linkActiveClass: 'active',
+  base: process.env.VUE_APP_ROUTER_BASE_URL || '/',
   routes: [
     {
       path: '/',
@@ -552,6 +554,10 @@ export default new Router({
         },
       ]
     },
+    {
+      path: '*/index.html',
+      redirect: '/'
+    },
     {
       path: '*',
       component: () =>

front/vue.config.js

@@ -10,7 +10,7 @@ if (process.env.BUNDLE_ANALYZE === '1') {
   plugins.push(new BundleAnalyzerPlugin())
 }
 module.exports = {
-  baseUrl: '/front/',
+  baseUrl: process.env.BASE_URL || '/front/',
   pages: {
     embed: {
       entry: 'src/embed.js',