Merge pull request #12849 from MisRob/docs-new-howtos

Developer documentation updates

Author: rtibbles

docs/getting_started.rst

@@ -335,7 +335,7 @@ To ensure a more efficient workflow, install appropriate editor plugins for Vue.
 Sample resources and data
 -------------------------
 
-Once you have the server running, proceed to import some channels and resources. To quickly import all available and supported Kolibri resource types, use the token ``nakav-mafak`` for the `Kolibri QA channel <https://kolibri-beta.learningequality.org/en/learn/#/topics/95a52b386f2c485cb97dd60901674a98>`__ (~350MB).
+Once you have the server running, proceed to import some channels and resources. To quickly import all available and supported Kolibri resource types, `import with the token <https://kolibri.readthedocs.io/en/latest/manage/resources.html?highlight=import#import-with-token>`__  ``nakav-mafak`` for the `Kolibri QA channel <https://kolibri-beta.learningequality.org/en/learn/#/topics/95a52b386f2c485cb97dd60901674a98>`__ (~350MB).
 
 
 Now you can create users, classes, lessons, etc manually. To auto-generate some sample user data you can also run:

docs/howtos/development_with_kds.md

@@ -1,4 +1,4 @@
-## Running Kolibri with local Kolibri Design System
+# Running Kolibri with local Kolibri Design System
 
 Kolibri uses components from [Kolibri Design System](https://github.com/learningequality/kolibri-design-system) (KDS). KDS is installed in Kolibri as a usual npm dependency.
 
@@ -12,4 +12,5 @@ yarn run devserver-with-kds <kds-path>
 
 where `<kds-path>` is the path of the local `kolibri-design-system` repository.
 
-It is recommended to use an absolute KDS path as some developers observed problems when running the command with a relative path.
+.. warning::
+  Some developers have reported issues when running the command with a relative path. If you encounter any problems, try using an absolute KDS path.

docs/howtos/index.rst

@@ -15,3 +15,4 @@ These guides are step by step guides for common tasks in getting started and wor
   rebasing_a_pull_request
   another_kolibri_instance
   development_with_kds
+  preview_on_mobile

docs/howtos/installing_pyenv.md

@@ -1,10 +1,10 @@
-## Installing pyenv
+# Installing pyenv
 
-### Prerequisites
+## Prerequisites
 
 [Git](https://git-scm.com/) installed.
 
-### Install
+## Install
 
 First check to see if you already have `pyenv` installed by running this in a terminal window:
 
@@ -91,7 +91,7 @@ The output of the command tells you to add certain lines to your startup files f
 
   **Proxy note**: If you use a proxy, export `http_proxy` and `https_proxy`, too.
 
-### Installation of pyenv on Windows
+## Installation of pyenv on Windows
 
 1. Run PowerShell terminal as Administrator
 2. Run the following installation command in the PowerShell terminal :
@@ -110,7 +110,7 @@ press Y not A, to execute Policy Change for this power shell only.
 
 then run the previous command again
 
-### Restart your shell
+## Restart your shell
 
 For the `PATH` changes to take effect, run the following command.
 
@@ -124,13 +124,13 @@ To check if pyenv is installed correctly, type:
 
   `pyenv version`
 
-### Install Python build dependencies
+## Install Python build dependencies
 
 [**Install Python build dependencies**](https://github.com/pyenv/pyenv/wiki#suggested-build-environment) before attempting to install a new Python version.
 
 You can now begin using Pyenv.
 
-### Installing a Python Version with PyEnv
+## Installing a Python Version with PyEnv
 
 Use the `pyenv` command in your terminal to install a recent version of Python:
 

docs/howtos/preview_on_mobile.md

@@ -0,0 +1,55 @@
+# Preview Kolibri on a mobile device
+
+_Note: This guide focuses on Kolibri as a web app rather than the Android version of Kolibri._
+
+Some tasks may require either an actual or simulated mobile device, such as a phone or tablet.
+
+## Browser development tools
+
+Most browsers provide ways to simulate mobile devices via their development tools. These tools are generally useful for testing:
+
+- Mobile viewports
+- Network and CPU throttling
+- Touch gestures
+
+Find specific guidance for the browser you are using.
+
+## Real mobile device
+
+Since browser development tools only offer an approximation, some tasks may require you to preview Kolibri on a real mobile device.
+
+### Option 1 (recommended)
+
+1. Ensure that the mobile device you wish to use for previewing Kolibri is connected to the same local network as your computer where you run the development server.
+2. Run the development server with `yarn python-devserver` and `yarn run watch --write-to-disk`
+3. In the section with URLs in the ``yarn python-devserver`` terminal output, locate Kolibri's ``http://A.B.C.D:8000/`` URL on the first line. Open a browser on the mobile device and navigate to that URL, where you should see Kolibri.
+
+```bash
+INFO     2024-11-19 15:14:21,967 Kolibri running on: http://A.B.C.D:8000/ # use this URL
+...
+INFO     2024-11-19 15:14:21,967 Kolibri running on: http://127.0.0.1:8000/
+```
+
+### Option 2
+
+1. Ensure that the mobile device you wish to use for previewing Kolibri is connected to the same local network as your computer where you run the development server.
+2. Run the development server with `yarn python-devserver` and `yarn build`
+3. In the section with URLs in the ``yarn python-devserver`` terminal output, locate Kolibri's ``http://A.B.C.D:8000/`` URL on the first line. Open a browser on the mobile device and navigate to that URL, where you should see Kolibri.
+
+```bash
+INFO     2024-11-19 15:14:21,967 Kolibri running on: http://A.B.C.D:8000/ # use this URL
+...
+INFO     2024-11-19 15:14:21,967 Kolibri running on: http://127.0.0.1:8000/
+```
+
+.. warning::
+   When running the development server as described above, you will need to rebuild frontend assets manually using ``yarn build`` after every change.
+
+.. tip::
+   Rebuild frontend assets faster by rebuilding only assets related to a plugin where you currently work. For example when developing on files of the Learn plugin, after the initial ``yarn build`` run, for all subsequent rebuilds only run ``yarn exec kolibri-tools build prod -- --plugins kolibri.plugins.learn`` instead of ``yarn build``. Use ``kolibri plugin list`` to see all plugins.
+
+### Troubleshooting
+
+- If you see an indefinite Kolibri loader on your mobile device, double-check that you are not running the development server with `yarn development-hot`. Follow the steps outlined above instead.
+
+- If you cannot access Kolibri at all, check your firewall, VPN, or similar network settings.

docs/howtos/pyenv_virtualenv.md

@@ -1,10 +1,10 @@
-## Using pyenv-virtualenv
+# Using pyenv-virtualenv
 
-### Virtual Environments
+## Virtual Environments
 
 Virtual environments allow a developer to have an encapsulated Python environment, using a specific version of Python, and with dependencies installed in a way that only affect the virtual environment. This is important as different projects or even different versions of the same project may have different dependencies, and virtual environments allow you to switch between them seamlessly and explicitly.
 
-### Using `pyenv virtualenv` with pyenv
+## Using `pyenv virtualenv` with pyenv
 
 To create a virtualenv for the Python version used with pyenv, run `pyenv virtualenv`, specifying the Python version you want and the name of the virtualenv directory. For example, because we can make a virtual environment for Kolibri using Python 3.9.9:
 
@@ -17,7 +17,7 @@ If you get 'command not found' or a similar error, and pyenv virtualenv is not i
 will create a virtualenv based on Python 3.9.9 under `$(pyenv root)/versions` in a
 folder called `kolibri-py3.9`.
 
-### List existing virtualenvs
+## List existing virtualenvs
 
 `pyenv virtualenvs` shows you the list of existing virtualenvs and `conda` environments.
 
@@ -30,7 +30,7 @@ $ pyenv virtualenvs
 There are two entries for each virtualenv, and the shorter one is just a symlink.
 
 
-### Activate virtualenv
+## Activate virtualenv
 
 If you want a virtual environment to always activate when you enter a certain directory, you can use the [`pyenv local`](https://github.com/pyenv/pyenv/blob/master/COMMANDS.md#pyenv-local) command.
 
@@ -47,7 +47,7 @@ pyenv activate kolibri-py3.9
 pyenv deactivate
 ```
 
-### Delete existing virtualenv
+## Delete existing virtualenv
 
 Removing the directories in `$(pyenv root)/versions` and `$(pyenv root)/versions/{version}/envs` will delete the virtualenv, or you can run:
 

docs/howtos/rebasing_a_pull_request.md

@@ -1,4 +1,4 @@
-## Rebasing a Pull Request
+# Rebasing a Pull Request
 
 On certain occasions, it might be necessary to redirect a pull request from the develop branch to the latest release branch, such as `release-v*` (e.g., `release-v0.16.x` when working on version 0.16), or vice versa. This guide outlines the steps for rebasing a feature branch related to your pull request while maintaining a clean commit history.