Merge pull request #4186 from mathesar-foundation/documentation

Documentation updates
mathesar-foundation · Jan 28, 2025 · 532876e · 532876e
2 parents a9108fc + 0faa9e2
commit 532876e
Show file tree

Hide file tree

Showing 19 changed files with 39 additions and 38 deletions.
diff --git a/docs/docs/administration/backup-restore.md b/docs/docs/administration/backup-restore.md
diff --git a/docs/docs/administration/debug.md b/docs/docs/administration/debug.md
@@ -1,12 +1,10 @@
-# Debug Mathesar
+# Debugging Mathesar
 
-For now, we only support turning on Debugging by using our special docker image. More methods will follow in future releases.
+If your Mathesar installation isn't working as expected, you can use our `mathesar-debug` Docker image that adds more debugging output to the console and more verbose errors in the browser when something goes wrong. The additional information logged should help you or the Mathesar team diagnose the installation issue.
 
 ## Use the debugging Mathesar docker image
 
-There is a debugging-enabled Mathesar docker image available at `mathesar/mathesar-debug` that is the same as the `mathesar/mathesar` image, except that it has more debugging output available in the console where it's run, and it also produces more verbose errors in the browser when something goes wrong.
-
-You can use this image to figure out (or to help the Mathesar team figure out) what's wrong if your Mathesar installation isn't working as expected. The procedure is to
+The debugging-enabled Mathesar docker image is available at the `mathesar/mathesar-debug` Docker repo. It's the same as the `mathesar/mathesar` image, other than adding more debugging output. To set it up:
 
 1. Run Mathesar with the `mathesar/mathesar-debug` image, and then
 1. Observe and report any additional output or clues to the Mathesar team.

diff --git a/docs/docs/administration/configuration.md → ...s/administration/environment-variables.md b/docs/docs/administration/configuration.md → ...s/administration/environment-variables.md
@@ -1,4 +1,4 @@
-# Configuring Mathesar with environment variables
+# Environment Variables for Configuration
 
 This page contains all available environment variables supported by Mathesar. See the specific installation guides for the applicable environment variables and instructions on how to set them.
 

diff --git a/docs/docs/administration/install-from-scratch.md b/docs/docs/administration/install-from-scratch.md
@@ -165,7 +165,7 @@ Then press <kbd>Enter</kbd> to customize this guide with your domain name.
         touch .env
         ```
 
-    1. Edit your `.env` file, adding [environment variables](./configuration.md) to configure Mathesar.
+    1. Edit your `.env` file, adding [environment variables](./environment-variables.md) to configure Mathesar.
 
         !!! example
             Your `.env` file should look something like this
@@ -182,7 +182,7 @@ Then press <kbd>Enter</kbd> to customize this guide with your domain name.
             ```
 
         !!! tip
-            To generate a [`SECRET_KEY`](./configuration.md#secret_key) you can use this [browser-based generator](https://djecrety.ir/) or run this command on MacOS or Linux:
+            To generate a [`SECRET_KEY`](./environment-variables.md#secret_key) you can use this [browser-based generator](https://djecrety.ir/) or run this command on MacOS or Linux:
 
             ```
             echo $(cat /dev/urandom | LC_CTYPE=C tr -dc 'a-zA-Z0-9' | head -c 50)

diff --git a/docs/docs/administration/install-via-docker-compose.md b/docs/docs/administration/install-via-docker-compose.md
@@ -116,4 +116,4 @@ If you'd like to use an external PostgreSQL server for Mathesar's internal datab
     psql -c 'create database mathesar_django;'
     ```
 
-1. Configure the [internal database environment variables](./configuration.md#db) to point to the database you just created. Ensure that you change the default values for the user, password, and host.
+1. Configure the [internal database environment variables](./environment-variables.md#db) to point to the database you just created. Ensure that you change the default values for the user, password, and host.
diff --git a/docs/docs/administration/uninstall.md b/docs/docs/administration/uninstall.md
@@ -1,4 +1,4 @@
-# Uninstall Mathesar
+# TODO: Uninstall Mathesar
 
 The uninstall instructions vary depending on the [installation method](../index.md#installing-mathesar) you chose. Select your installation method below to proceed.
 
@@ -29,7 +29,7 @@ The uninstall instructions vary depending on the [installation method](../index.
 {% include 'snippets/uninstall-schemas.md' %}
 
 
-## Uninstall a Guided script or Docker compose installation of Mathesar
+## Uninstall a guided script or Docker compose installation of Mathesar
 
 1. Remove all Mathesar Docker images and containers.
 

diff --git a/docs/docs/administration/upgrade.md b/docs/docs/administration/upgrade.md
@@ -1,9 +1,9 @@
 # Upgrade Mathesar
 
+!!! warning "Mathesar cannot be upgraded to version 0.2.0"
+    You'll need to reinstall Mathesar to use Mathesar 0.2.0, our initial beta release. Upgrading from our alpha versions is not supported.
+
 The steps to upgrade Mathesar vary by release.
 
 1. First find the release notes for the version to which you'd like to upgrade.
-1. Look at the bottom of the release notes for upgrade instructions.
-
-!!! warning "Caveats"
-    - Upgrading to Mathesar 0.2.0 from prior versions is not supported. You'll need to reinstall Mathesar to use this version.
+1. Look at the bottom of the release notes for upgrade instructions.
diff --git a/docs/docs/analytics.md → ...s/administration/usage-data-collection.md b/docs/docs/analytics.md → ...s/administration/usage-data-collection.md
@@ -1,6 +1,10 @@
-# Optional Data Collection
+# Usage Data Collection
 
-If you allow Mathesar to collect analytics data, the following information is sent every 24 hours:
+You can opt-in to allow Mathesar to gather anonymized usage data. This is very valuable to us to help us improve Mathesar’s features, performance, and stability, through understanding how Mathesar is being used, enabling us to identify areas to improve the user experience, and allowing us to track adoption and ensure the reliability of the tool.
+
+## Data Sent
+
+When you've opted-in to usage data collection, the following information is sent every 24 hours:
 
 - **created_at**: A timestamp giving the time the report was created.
 - **installation_id**: This is a randomized UUID unique to your Mathesar installation.
@@ -14,4 +18,6 @@ If you allow Mathesar to collect analytics data, the following information is se
 - **connected_database_record_count**: The approximate number of records in all tables connected to your Mathesar installation.
 - **exploration_count**: The number of Explorations you've created in Mathesar.
 
-If you'd like to see an actual report from your running Mathesar installation, go to the path `/info/analytics_sample_report/` at the domain where you connect to Mathesar. You can also call the RPC function [`analytics.view_report`](api/methods.md##Analytics).
+## Viewing Actual Reports
+
+If you'd like to see an actual report from your running Mathesar installation, go to the path `/info/analytics_sample_report/` at the domain where you connect to Mathesar. You can also call the RPC function [`analytics.view_report`](../../api/methods#analytics.view_report).
diff --git a/docs/docs/releases/0.1.4.md b/docs/docs/releases/0.1.4.md
@@ -237,7 +237,7 @@ If you followed our [Docker Compose installation instructions](../administration
 
     1. Double-check the rest of the configuration:
 
-        - You should have your [`SECRET_KEY` variable](../administration/configuration.md#secret_key) defined.
+        - You should have your [`SECRET_KEY` variable](../administration/environment-variables.md#secret_key) defined.
         - If hosting on the internet, you should have a `DOMAIN_NAME` variable defined.
 
 1. Initialize new Mathesar installation
@@ -311,7 +311,7 @@ If you installed Mathesar [from scratch](../administration/install-from-scratch.
     source ./mathesar-venv/bin/activate
     ```
 
-1. Update your environment variables according to the [the new configuration specification](../administration/configuration.md#secret_key). In particular, you must put the connection info for the internal DB into new `POSTGRES_*` variables. The `DJANGO_DATABASE_URL` variable is no longer supported.
+1. Update your environment variables according to the [the new configuration specification](../administration/environment-variables.md#secret_key). In particular, you must put the connection info for the internal DB into new `POSTGRES_*` variables. The `DJANGO_DATABASE_URL` variable is no longer supported.
 
 1. Add the environment variables to the shell before running Django commands
 

diff --git a/docs/docs/releases/0.1.6.md b/docs/docs/releases/0.1.6.md
@@ -120,7 +120,7 @@ If you installed Mathesar [from scratch](../administration/install-from-scratch.
     ```
 
 1. You can skip the following if you're upgrading from versions 0.1.4 and above.
-    - If you're upgrading from versions <= 0.1.3, update your environment variables according to the [the new configuration specification](../administration/configuration.md#db).
+    - If you're upgrading from versions <= 0.1.3, update your environment variables according to the [the new configuration specification](../administration/environment-variables.md#db).
     - In particular, you must put the connection info for the internal DB into new `POSTGRES_*` variables. The `DJANGO_DATABASE_URL` variable is no longer supported.
 
 1. Add the environment variables to the shell before running Django commands

diff --git a/docs/docs/releases/0.1.7.md b/docs/docs/releases/0.1.7.md
@@ -92,7 +92,7 @@ If you installed Mathesar [from scratch](../administration/install-from-scratch.
     ```
 
 1. You can skip the following if you're upgrading from versions 0.1.4 and above.
-    - If you're upgrading from versions <= 0.1.3, update your environment variables according to the [the new configuration specification](../administration/configuration.md#db).
+    - If you're upgrading from versions <= 0.1.3, update your environment variables according to the [the new configuration specification](../administration/environment-variables.md#db).
     - In particular, you must put the connection info for the internal DB into new `POSTGRES_*` variables. The `DJANGO_DATABASE_URL` variable is no longer supported.
 
 1. Add the environment variables to the shell before running Django commands

diff --git a/docs/docs/releases/0.2.0.md b/docs/docs/releases/0.2.0.md
@@ -578,7 +578,7 @@ For these instructions, you'll need to be familiar enough with your setup to log
     ```
 
 1. You can skip the following if you're upgrading from versions 0.1.4 and above.
-    - If you're upgrading from versions <= 0.1.3, update your environment variables according to the [the new configuration specification](../administration/configuration.md#db).
+    - If you're upgrading from versions <= 0.1.3, update your environment variables according to the [the new configuration specification](../administration/environment-variables.md#db).
     - In particular, you must put the connection info for the internal DB into new `POSTGRES_*` variables. The `DJANGO_DATABASE_URL` variable is no longer supported.
 
 1. Add the environment variables to the shell before running Django commands

diff --git a/docs/docs/user-guide/databases.md b/docs/docs/user-guide/databases.md
@@ -18,7 +18,7 @@ Click the **Connect Database** button from the home page of your Mathesar applic
 
 Once you've connected a database, you can navigate to Mathesar's page for it where you can browse the database's [schemas](./schemas.md) and configure various settings for it.
 
-Mathesar will remember the connection even after the application is shut down. Your Mathesar [user](./users.md) will be added as a [collaborator](./collaborators.md) on the database (along with the PostgreSQL [role](./roles.md) you entered). The password you entered for that role will be stored in Mathesar's [internal database](#internal), encrypted using Mathesar's [SECRET_KEY](../administration/configuration.md#secret_key).
+Mathesar will remember the connection even after the application is shut down. Your Mathesar [user](./users.md) will be added as a [collaborator](./collaborators.md) on the database (along with the PostgreSQL [role](./roles.md) you entered). The password you entered for that role will be stored in Mathesar's [internal database](#internal), encrypted using Mathesar's [SECRET_KEY](../administration/environment-variables.md#secret_key).
 
 ## Creating a new database
 

diff --git a/docs/docs/user-guide/roles.md b/docs/docs/user-guide/roles.md
@@ -17,7 +17,7 @@ Other permission systems commonly have a _separate_ concept of "groups", wherein
 
 To see the roles available on your server, navigate to the **Database Settings** tab within the page for one of your connected databases. From there, you'll be able to add roles, drop roles, and edit role inheritance.
 
-Role passwords are stored in Mathesar's [internal database](./databases.md#internal) and encrypted with your [SECRET_KEY](../administration/configuration.md#secret_key).
+Role passwords are stored in Mathesar's [internal database](./databases.md#internal) and encrypted with your [SECRET_KEY](../administration/environment-variables.md#secret_key).
 
 Renaming roles and modifying role properties (e.g. `LOGIN` status) is not supported within Mathesar.
 

diff --git a/docs/docs/user-guide/stored-role-passwords.md b/docs/docs/user-guide/stored-role-passwords.md
@@ -11,7 +11,7 @@ If the password for a role is modified within PostgreSQL, you'll need to update
 How passwords are stored:
 
 - Passwords are stored in Mathesar's [internal database](./databases.md#internal).
-- They are encrypted at rest with your [SECRET_KEY](../administration/configuration.md#secret_key) generated at installation time.
+- They are encrypted at rest with your [SECRET_KEY](../administration/environment-variables.md#secret_key) generated at installation time.
 - They are stored per-database-_server_. This means that if you connect two databases on the same server, then the same role password can be used for both databases.
 
 To manage the stored passwords:

diff --git a/docs/mkdocs.yml b/docs/mkdocs.yml
@@ -9,13 +9,12 @@ nav:
   - Administration:
       - Install using Docker Compose: administration/install-via-docker-compose.md
       - Install from scratch: administration/install-from-scratch.md
-      - Configuration: administration/configuration.md
-      - Backup & Restore: administration/backup-restore.md
+      - Environment Variables: administration/environment-variables.md
       - Upgrade Mathesar: administration/upgrade.md
       - Uninstall Mathesar: administration/uninstall.md
-      - Debug Mathesar: administration/debug.md
-      - Version Support: administration/version-support.md
-      - Optional Data Collection: analytics.md
+      - Debugging Mathesar: administration/debug.md
+      - Postgres & Python Versions: administration/version-support.md
+      - Usage Data Collection: administration/usage-data-collection.md
   - User Guide:
       - Introduction: user-guide/index.md
       - Your data in PostgreSQL:
@@ -66,7 +65,8 @@ plugins:
         "api/rest.md": "api/index.md"
         "user-guide/glossary.md": "user-guide/index.md"
         "user-guide/permissions.md": "user-guide/access-control.md"
-        "configuration/env-variables.md": "administration/configuration.md"
+        "configuration/env-variables.md": "administration/environment-variables.md"
+        "administration/configuration.md": "administration/environment-variables.md"
         "installation/docker-compose/index.md": "administration/install-via-docker-compose.md"
         "installation/build-from-source/index.md": "administration/install-from-scratch.md"
   - macros

diff --git a/mathesar/templates/installation/complete_installation.html b/mathesar/templates/installation/complete_installation.html
@@ -253,7 +253,7 @@ <h1>{% translate "Finish Setting Up Mathesar" %}</h1>
             {% translate "Share anonymous usage data periodically to help us improve features." %}
             {% translate "No personal data is collected, and you can change this setting anytime." %}
             <!-- TODO_BETA: Add correct link to analytics information docs-page/website -->
-            <a class="help-link" href="https://docs.mathesar.org/analytics/" target="_blank">
+            <a class="help-link" href="https://docs.mathesar.org/administration/usage-data-collection/" target="_blank">
               {% translate "See what's shared." %}
             </a>
           </div>

diff --git a/mathesar_ui/src/pages/admin-privacy/PrivacyPage.svelte b/mathesar_ui/src/pages/admin-privacy/PrivacyPage.svelte
@@ -66,7 +66,7 @@
       {/if}
       <div slot="help">
         <div>{$_('anonymous_usage_data_collection_help')}</div>
-        <DocsLink page="analytics">
+        <DocsLink page="usageDataCollection">
           <span>{$_('see_whats_shared')}</span>
           <Icon {...iconExternalHyperlink} />
         </DocsLink>

diff --git a/mathesar_ui/src/routes/urls.ts b/mathesar_ui/src/routes/urls.ts
@@ -141,7 +141,7 @@ export function getSharedExplorationPageUrl(slug: string): string {
 }
 
 const docsPages = {
-  analytics: '/analytics/',
+  usageDataCollection: '/administration/usage-data-collection/',
   collaborators: '/user-guide/collaborators/',
   databasePermissions: '/user-guide/databases/#permissions',
   databases: '/user-guide/databases/',