Add documentation for the create-user command #458

Signed-off-by: Thomas Druez <tdruez@nexb.com>

docs/command-line-interface.rst

@@ -238,3 +238,37 @@ Deletes a project and its related work directories.
 Optional arguments:
 
 - ``--no-input`` Does not prompt the user for input of any kind.
+
+
+.. _cli_create_user:
+
+`$ scanpipe create-user <username>`
+-----------------------------------
+
+.. note:: This command is to be used when ScanCode.io's authentication system
+  :ref:`scancodeio_settings_require_authentication` is enabled.
+
+Creates a user and generates an API key for authentication.
+
+You will be prompted for a password. After you enter one, the user will be created
+immediately.
+
+The API key for the new user account will be displayed on the terminal output.
+
+.. code-block:: console
+
+    User <username> created with API key: abcdef123456
+
+The API key can also be retrieved from the :guilabel:`Profile settings` menu in the UI.
+
+.. warning::
+    Your API key is like a password and should be treated with the same care.
+
+By default, this command will prompt for a password for the new user account.
+When run non-interactively with the ``--no-input`` option, no password will be set,
+and the user account will only be able to authenticate with the REST API using its
+API key.
+
+Optional arguments:
+
+- ``--no-input`` Does not prompt the user for input of any kind.

docs/rest-api.rst

@@ -12,9 +12,9 @@ local development setup.
 Authentication
 --------------
 
-When the authentication setting is enabled on a ScanCode.io instance—disabled by
-default—you will have to include an authentication token ``API key`` in the
-Authorization HTTP header of each request.
+When the authentication setting :ref:`scancodeio_settings_require_authentication`
+is enabled on a ScanCode.io instance (disabled by default), you will have to include
+an authentication token ``API key`` in the Authorization HTTP header of each request.
 
 The key should be prefixed by the string literal "Token" with whitespace
 separating the two strings. For example::

docs/scancodeio-settings.rst

@@ -44,17 +44,11 @@ The authentication system can be enable with this settings::
 Once enabled, all the Web UI views and REST API endpoints will force the user to login
 to gain access.
 
-Create a superuser with the following command and follow the prompts:
-$ ./manage.py createsuperuser
+A management command :ref:`cli_create_user` is available to create users and
+generate their API key for authentication.
 
-Generate a unique API key for this user using providing the username used in the previous command:
-$ ./manage.py drf_create_token USERNAME
-Generated token 3bf81af7f100548219e73ec69669ee7acabf8fd8 for user USERNAME
-
-The 3bf81af7f100548219e73ec69669ee7acabf8fd8 valie is your API key.
-
-See :ref:`rest_api_authentication` for details on the``API key`` authentication system
-in the REST API.
+See :ref:`rest_api_authentication` for details on using the ``API key``
+authentication system in the REST API.
 
 .. _scancodeio_settings_workspace_location:
 

scanpipe/tests/test_commands.py

@@ -530,4 +530,3 @@ def test_scanpipe_management_command_create_user(self):
         )
         with self.assertRaisesMessage(CommandError, expected):
             call_command("create-user", "--no-input", username)
-