Merge branch 'config-docs' into 'develop'

Documentation for .env variables

See merge request funkwhale/funkwhale!1095

.gitlab-ci.yml

@@ -71,7 +71,7 @@ review_docs:
     - cd docs
     - apt-get update
     - apt-get install -y graphviz
-    - pip install sphinx sphinx_rtd_theme
+    - pip install sphinx sphinx_rtd_theme django-environ django
   script:
     - ./build_docs.sh
   cache:

docs/Dockerfile

 FROM python:3.6
 
 RUN apt-get update && apt-get install -y graphviz
-RUN pip install sphinx livereload sphinx_rtd_theme
+RUN pip install sphinx livereload sphinx_rtd_theme django-environ django
 WORKDIR /app/docs

docs/admin/configuration.rst

 Instance configuration
 ======================
 
-General configuration is achieved using two type of settings.
+General configuration is achieved using two type of settings:
+:ref:`environment variables <environment-variables>` and
+:ref:`instance settings <instance-settings>`.
+
+.. _environment-variables:
 
 Environment variables
 ---------------------
 
 Those are located in your ``.env`` file, which you should have created
-during installation.
+during installation. A full list of available variables can be seen
+:ref:`below <environment-variables>`.
 
 Options from this file are heavily commented, and usually target lower level
 and technical aspects of your instance, such as database credentials.
@@ -33,7 +38,7 @@ and technical aspects of your instance, such as database credentials.
 Instance settings
 -----------------
 
-Those settings are stored in database and do not require a restart of your
+These settings are stored in the database and do not require a restart of your
 instance after modification. They typically relate to higher level configuration,
 such your instance description, signup policy and so on.
 
@@ -42,7 +47,7 @@ you have the required permissions. The URL is ``/manage/settings``, and
 you will also find a link to this page in the sidebar.
 
 If you plan to use acoustid and external imports
-(e.g. with the youtube backends), you should edit the corresponding
+(e.g. with the YouTube backends), you should edit the corresponding
 settings in this interface.
 
 .. note::
@@ -58,113 +63,114 @@ settings in this interface.
 Configuration reference
 -----------------------
 
-.. _setting-ACCOUNT_EMAIL_VERIFICATION_ENFORCE:
-
-``ACCOUNT_EMAIL_VERIFICATION_ENFORCE``
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-
-Determine wether users need to verify their email address before using the service. Enabling this can be useful
-to reduce spam or bots accounts, however, you'll need to configure a SMTP server so that your users can receive the
-verification emails.
-
-Note that regardless of the setting value, superusers created through the command line will never require verification.
-
-Default: ``false``
-
-.. _setting-EMAIL_CONFIG:
-
-``EMAIL_CONFIG``
-^^^^^^^^^^^^^^^^
-
-Determine how emails are sent.
-
-Default: ``consolemail://``
-
-Possible values:
-
-- ``consolemail://``: Output sent emails to stdout
-- ``dummymail://``: Completely discard sent emails
-- ``smtp://user:password@youremail.host:25``: Send emails via SMTP via youremail.host on port 25, without encryption, authenticating as user "user" with password "password"
-- ``smtp+ssl://user:password@youremail.host:465``: Send emails via SMTP via youremail.host on port 465, using SSL encryption, authenticating as user "user" with password "password"
-- ``smtp+tls://user:password@youremail.host:587``: Send emails via SMTP via youremail.host on port 587, using TLS encryption, authenticating as user "user" with password "password"
-
-.. note::
-
-    If ``user`` or ``password`` contain special characters (eg.
-    ``noreply@youremail.host`` as ``user``), be sure to urlencode them, using
-    for example the command:
-    ``python3 -c 'import urllib.parse; print(urllib.parse.quote_plus("noreply@youremail.host"))'``
-    (returns ``noreply%40youremail.host``)
-
-
-.. _setting-DEFAULT_FROM_EMAIL:
-
-``DEFAULT_FROM_EMAIL``
-^^^^^^^^^^^^^^^^^^^^^^
-
-The email address to use to send email.
-
-Default: ``Funkwhale <noreply@yourdomain>``
-
-.. note::
-
-    Both the forms ``Funkwhale <noreply@yourdomain>`` and
-    ``noreply@yourdomain`` work.
-
-
-.. _setting-MUSIC_DIRECTORY_PATH:
-
-``MUSIC_DIRECTORY_PATH``
-^^^^^^^^^^^^^^^^^^^^^^^^
-
-Default: ``None``
-
-The path on your server where Funkwhale can import files using :ref:`in-place import
-<in-place-import>`. It must be readable by the webserver and Funkwhale
-api and worker processes.
-
-On docker installations, we recommend you use the default of ``/music``
-for this value. For non-docker installation, you can use any absolute path.
-``/srv/funkwhale/data/music`` is a safe choice if you don't know what to use.
-
-.. note:: This path should not include any trailing slash
-
-.. warning::
-
-   You need to adapt your :ref:`reverse-proxy configuration<reverse-proxy-setup>` to
-   serve the directory pointed by ``MUSIC_DIRECTORY_PATH`` on
-   ``/_protected/music`` URL.
-
-.. _setting-MUSIC_DIRECTORY_SERVE_PATH:
-
-``MUSIC_DIRECTORY_SERVE_PATH``
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-
-Default: :ref:`setting-MUSIC_DIRECTORY_PATH`
-
-When using Docker, the value of :ref:`setting-MUSIC_DIRECTORY_PATH` in your containers
-may differ from the real path on your host. Assuming you have the following directive
-in your :file:`docker-compose.yml` file::
-
-    volumes:
-      - /srv/funkwhale/data/music:/music:ro
-
-Then, the value of :ref:`setting-MUSIC_DIRECTORY_SERVE_PATH` should be
-``/srv/funkwhale/data/music``. This must be readable by the webserver.
-
-On non-docker setup, you don't need to configure this setting.
-
-.. note:: This path should not include any trailing slash
-
-.. _setting-REVERSE_PROXY_TYPE:
-
-``REVERSE_PROXY_TYPE``
-^^^^^^^^^^^^^^^^^^^^^^
-
-Default: ``nginx``
-
-The type of reverse-proxy behind which Funkwhale is served. Either ``apache2``
-or ``nginx``. This is only used if you are using in-place import.
+Pod
+^^^
+
+.. autodata:: config.settings.common.FUNKWHALE_HOSTNAME
+    :annotation:
+.. autodata:: config.settings.common.FUNKWHALE_PROTOCOL
+
+Database and redis
+^^^^^^^^^^^^^^^^^^
+
+.. autodata:: config.settings.common.DATABASE_URL
+    :annotation:
+.. autodata:: config.settings.common.DB_CONN_MAX_AGE
+.. autodata:: config.settings.common.CACHE_URL
+    :annotation:
+.. autodata:: config.settings.common.CELERY_BROKER_URL
+    :annotation:
+
+Accounts and registration
+^^^^^^^^^^^^^^^^^^^^^^^^^
+
+.. autodata:: config.settings.common.ACCOUNT_EMAIL_VERIFICATION_ENFORCE
+    :annotation:
+.. autodata:: config.settings.common.USERS_INVITATION_EXPIRATION_DAYS
+    :annotation:
+.. autodata:: config.settings.common.DISABLE_PASSWORD_VALIDATORS
+    :annotation:
+.. autodata:: config.settings.common.ACCOUNT_USERNAME_BLACKLIST
+    :annotation:
+.. autodata:: config.settings.common.AUTH_LDAP_ENABLED
+    :annotation:
+
+Media storage and serving
+^^^^^^^^^^^^^^^^^^^^^^^^^
+
+.. autodata:: config.settings.common.MEDIA_URL
+    :annotation: = https://mypod.audio/media/
+.. autodata:: config.settings.common.MEDIA_ROOT
+    :annotation: = /srv/funkwhale/data/media
+.. autodata:: config.settings.common.PROXY_MEDIA
+    :annotation: = true
+.. autodata:: config.settings.common.EXTERNAL_MEDIA_PROXY_ENABLED
+.. autodata:: config.settings.common.ATTACHMENTS_UNATTACHED_PRUNE_DELAY
+    :annotation: = true
+.. autodata:: config.settings.common.REVERSE_PROXY_TYPE
+.. autodata:: config.settings.common.PROTECT_FILES_PATH
+
+Audio acquisition
+^^^^^^^^^^^^^^^^^
+
+.. autodata:: config.settings.common.MUSIC_DIRECTORY_PATH
+.. autodata:: config.settings.common.MUSIC_DIRECTORY_SERVE_PATH
+
+S3 Storage
+^^^^^^^^^^
+
+.. autodata:: config.settings.common.AWS_QUERYSTRING_AUTH
+.. autodata:: config.settings.common.AWS_QUERYSTRING_EXPIRE
+.. autodata:: config.settings.common.AWS_ACCESS_KEY_ID
+.. autodata:: config.settings.common.AWS_SECRET_ACCESS_KEY
+.. autodata:: config.settings.common.AWS_STORAGE_BUCKET_NAME
+.. autodata:: config.settings.common.AWS_S3_CUSTOM_DOMAIN
+.. autodata:: config.settings.common.AWS_S3_ENDPOINT_URL
+.. autodata:: config.settings.common.AWS_S3_REGION_NAME
+.. autodata:: config.settings.common.AWS_LOCATION
+
+API configuration
+^^^^^^^^^^^^^^^^^
+
+.. autodata:: config.settings.common.THROTTLING_ENABLED
+.. autodata:: config.settings.common.THROTTLING_RATES
+.. autodata:: config.settings.common.ADMIN_URL
+.. autodata:: config.settings.common.EXTERNAL_REQUESTS_VERIFY_SSL
+.. autodata:: config.settings.common.EXTERNAL_REQUESTS_TIMEOUT
+
+Federation
+^^^^^^^^^^
+
+.. autodata:: config.settings.common.FEDERATION_OBJECT_FETCH_DELAY
+.. autodata:: config.settings.common.FEDERATION_DUPLICATE_FETCH_DELAY
+
+Metadata
+^^^^^^^^
+
+.. autodata:: config.settings.common.TAGS_MAX_BY_OBJ
+.. autodata:: config.settings.common.MUSICBRAINZ_HOSTNAME
+.. autodata:: config.settings.common.MUSICBRAINZ_CACHE_DURATION
+
+Channels and podcasts
+^^^^^^^^^^^^^^^^^^^^^
+
+.. autodata:: config.settings.common.PODCASTS_RSS_FEED_REFRESH_DELAY
+.. autodata:: config.settings.common.PODCASTS_RSS_FEED_MAX_ITEMS
+.. autodata:: config.settings.common.PODCASTS_THIRD_PARTY_VISIBILITY
+
+Subsonic
+^^^^^^^^
+
+.. autodata:: config.settings.common.SUBSONIC_DEFAULT_TRANSCODING_FORMAT
+
+Other settings
+^^^^^^^^^^^^^^
+
+.. autodata:: config.settings.common.INSTANCE_SUPPORT_MESSAGE_DELAY
+.. autodata:: config.settings.common.FUNKWHALE_SUPPORT_MESSAGE_DELAY
+.. autodata:: config.settings.common.MIN_DELAY_BETWEEN_DOWNLOADS_COUNT
+.. autodata:: config.settings.common.MARKDOWN_EXTENSIONS
+.. autodata:: config.settings.common.LINKIFIER_SUPPORTED_TLDS
 
 User permissions
 ----------------
@@ -194,7 +200,7 @@ to users at ``/api/admin/users/user/``.
 Front-end settings
 ------------------
 
-We offer a basic mechanism to customize the behaviour and look and feel of Funkwhale's Web UI.
+We offer a basic mechanism to customize the behavior and look and feel of Funkwhale's Web UI.
 To use any of the options below, you will need to create a custom JSON configuration file and serve it
 on ``https://yourinstanceurl/settings.json``.
 
@@ -296,7 +302,7 @@ On nginx, add the following snippet to your vhost config::
         alias /srv/funkwhale/custom;
     }
 
-On apache, use the following one::
+On apache, use the following::
 
     Alias /custom /srv/funkwhale/custom
 

docs/conf.py

@@ -26,6 +26,16 @@ sys.path.insert(0, os.path.abspath("../api"))
 
 import funkwhale_api  # NOQA
 
+FUNKWHALE_CONFIG = {
+    "FUNKWHALE_URL": "mypod.funkwhale",
+    "FUNKWHAL_PROTOCOL": "https",
+    "DATABASE_URL": "postgres://localhost:5432/db",
+    "AWS_ACCESS_KEY_ID": 'my_access_key',
+    "AWS_SECRET_ACCESS_KEY": 'my_secret_key',
+    "AWS_STORAGE_BUCKET_NAME": 'my_bucket',
+}
+for key, value in FUNKWHALE_CONFIG.items():
+    os.environ[key] = value
 # -- General configuration ------------------------------------------------
 
 # If your documentation needs a minimal Sphinx version, state it here.
@@ -35,8 +45,9 @@ import funkwhale_api  # NOQA
 # Add any Sphinx extension module names here, as strings. They can be
 # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
 # ones.
-extensions = ["sphinx.ext.graphviz"]
-
+extensions = ["sphinx.ext.graphviz", "sphinx.ext.autodoc"]
+autodoc_mock_imports = ["celery", "django_auth_ldap", "ldap"]
+add_module_names = False
 # Add any paths that contain templates here, relative to this directory.
 templates_path = ["_templates"]
 

docs/serve.py

@@ -6,5 +6,5 @@ call(["python", "-m", "sphinx", ".", "/tmp/_build"])
 from livereload import Server, shell
 
 server = Server()
-server.watch(".", shell("python -m sphinx . /tmp/_build"))
+server.watch("..", shell("python -m sphinx . /tmp/_build"))
 server.serve(root="/tmp/_build/", liveport=35730, port=8001, host="0.0.0.0")