From eceb954486b5a94b44afa0faa0b1e635ffbec32a Mon Sep 17 00:00:00 2001 From: Michaela Robosova Date: Fri, 15 Nov 2024 16:50:10 +0100 Subject: [PATCH 1/5] Format as warning --- docs/howtos/development_with_kds.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/docs/howtos/development_with_kds.md b/docs/howtos/development_with_kds.md index fff96282703..958f45dc6fe 100644 --- a/docs/howtos/development_with_kds.md +++ b/docs/howtos/development_with_kds.md @@ -12,4 +12,5 @@ yarn run devserver-with-kds where `` 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. From 435506967dee466308a78bbb936cf13cda2cfaa5 Mon Sep 17 00:00:00 2001 From: Michaela Robosova Date: Fri, 15 Nov 2024 16:55:46 +0100 Subject: [PATCH 2/5] Consistent heading levels --- docs/howtos/development_with_kds.md | 2 +- docs/howtos/installing_pyenv.md | 14 +++++++------- docs/howtos/pyenv_virtualenv.md | 12 ++++++------ docs/howtos/rebasing_a_pull_request.md | 2 +- 4 files changed, 15 insertions(+), 15 deletions(-) diff --git a/docs/howtos/development_with_kds.md b/docs/howtos/development_with_kds.md index 958f45dc6fe..f53aab8fdc0 100644 --- a/docs/howtos/development_with_kds.md +++ b/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. diff --git a/docs/howtos/installing_pyenv.md b/docs/howtos/installing_pyenv.md index c10292031ec..fa87b575acf 100644 --- a/docs/howtos/installing_pyenv.md +++ b/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: diff --git a/docs/howtos/pyenv_virtualenv.md b/docs/howtos/pyenv_virtualenv.md index 918087b535b..c19f6928bbf 100644 --- a/docs/howtos/pyenv_virtualenv.md +++ b/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: diff --git a/docs/howtos/rebasing_a_pull_request.md b/docs/howtos/rebasing_a_pull_request.md index a1c0f014f81..6c8c2d9d409 100644 --- a/docs/howtos/rebasing_a_pull_request.md +++ b/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. From 3ba70a67d74bd0d95ebfda4b7819e140099c45a2 Mon Sep 17 00:00:00 2001 From: Michaela Robosova Date: Fri, 15 Nov 2024 17:00:39 +0100 Subject: [PATCH 3/5] Link how to import with token --- docs/getting_started.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/getting_started.rst b/docs/getting_started.rst index 351777bd9e2..8aeae8c106c 100644 --- a/docs/getting_started.rst +++ b/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 `__ (~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 `__ ``nakav-mafak`` for the `Kolibri QA channel `__ (~350MB). Now you can create users, classes, lessons, etc manually. To auto-generate some sample user data you can also run: From b3e770697bfed79fa7756710f9e936d741b7cb68 Mon Sep 17 00:00:00 2001 From: Michaela Robosova Date: Fri, 15 Nov 2024 17:52:30 +0100 Subject: [PATCH 4/5] Add mobile device guide --- docs/howtos/index.rst | 1 + docs/howtos/preview_on_mobile.md | 48 ++++++++++++++++++++++++++++++++ 2 files changed, 49 insertions(+) create mode 100644 docs/howtos/preview_on_mobile.md diff --git a/docs/howtos/index.rst b/docs/howtos/index.rst index 4e2c544b02e..3bc2dc4d845 100644 --- a/docs/howtos/index.rst +++ b/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 diff --git a/docs/howtos/preview_on_mobile.md b/docs/howtos/preview_on_mobile.md new file mode 100644 index 00000000000..8382e114878 --- /dev/null +++ b/docs/howtos/preview_on_mobile.md @@ -0,0 +1,48 @@ +# 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. Find your computer's IP address +4. Open a browser on the mobile device and navigate to your computer's IP address with port `:8000`, `http://x.x.x.x:8000`. There, you should see Kolibri. + +.. tip:: + In ``yarn run watch --write-to-disk`` command terminal output, you can find your computer's IP address on the line ``[webpack-dev-server] On Your Network (IPv4): http://x.x.x.x:3000/``. + +### 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. Find your computer's IP address +4. Open a browser on the mobile device and navigate to your computer's IP address with port `:8000`, `http://x.x.x.x:8000`. There, you should see Kolibri. + +.. 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. From e047e1b81fdd8ab9c774248d5d88628af6e7fd05 Mon Sep 17 00:00:00 2001 From: Michaela Robosova Date: Mon, 16 Dec 2024 15:52:00 +0100 Subject: [PATCH 5/5] Improve guidance on getting the correct URL --- docs/howtos/preview_on_mobile.md | 19 +++++++++++++------ 1 file changed, 13 insertions(+), 6 deletions(-) diff --git a/docs/howtos/preview_on_mobile.md b/docs/howtos/preview_on_mobile.md index 8382e114878..8467c193ce9 100644 --- a/docs/howtos/preview_on_mobile.md +++ b/docs/howtos/preview_on_mobile.md @@ -22,18 +22,25 @@ Since browser development tools only offer an approximation, some tasks may requ 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. Find your computer's IP address -4. Open a browser on the mobile device and navigate to your computer's IP address with port `:8000`, `http://x.x.x.x:8000`. There, you should see Kolibri. +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. -.. tip:: - In ``yarn run watch --write-to-disk`` command terminal output, you can find your computer's IP address on the line ``[webpack-dev-server] On Your Network (IPv4): http://x.x.x.x:3000/``. +```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. Find your computer's IP address -4. Open a browser on the mobile device and navigate to your computer's IP address with port `:8000`, `http://x.x.x.x:8000`. There, you should see Kolibri. +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.