You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@airavata.apache.org by ma...@apache.org on 2021/06/17 16:41:24 UTC
[airavata-django-portal] 01/05: tutorial: tabbed instructions for
different OS/environments
This is an automated email from the ASF dual-hosted git repository.
machristie pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/airavata-django-portal.git
commit 2169ef78dbeac9db1d99557143dbcdf5942175bd
Author: Marcus Christie <ma...@apache.org>
AuthorDate: Thu Jun 17 09:48:04 2021 -0400
tutorial: tabbed instructions for different OS/environments
---
docs/assets/css/pymdownx.tabbed.css | 46 ++++++++
docs/tutorial/custom_ui_tutorial.md | 230 +++++++++++++++++-------------------
mkdocs.yml | 4 +
requirements-dev.txt | 3 +-
4 files changed, 162 insertions(+), 121 deletions(-)
diff --git a/docs/assets/css/pymdownx.tabbed.css b/docs/assets/css/pymdownx.tabbed.css
new file mode 100644
index 0000000..6a744c2
--- /dev/null
+++ b/docs/assets/css/pymdownx.tabbed.css
@@ -0,0 +1,46 @@
+.tabbed-set {
+ display: flex;
+ position: relative;
+ flex-wrap: wrap;
+ margin-bottom: 1em;
+}
+
+.tabbed-set .highlight {
+ background: #ddd;
+}
+
+.tabbed-set .tabbed-content {
+ display: none;
+ order: 99;
+ width: 100%;
+ background-color: #e7f2fa;
+ padding: 0.25em;
+}
+
+.tabbed-set label {
+ width: auto;
+ /* margin: 0 0.5em; */
+ margin: 0;
+ padding: 0.25em 0.5em;
+ /* font-size: 120%; */
+ font-weight: 700;
+ cursor: pointer;
+}
+
+.tabbed-set input {
+ position: absolute;
+ opacity: 0;
+}
+
+.tabbed-set input:nth-child(n + 1) {
+ color: #333333;
+}
+
+.tabbed-set input:nth-child(n + 1):checked + label {
+ /* color: #ff5252; */
+ background-color: #e7f2fa;
+}
+
+.tabbed-set input:nth-child(n + 1):checked + label + .tabbed-content {
+ display: block;
+}
diff --git a/docs/tutorial/custom_ui_tutorial.md b/docs/tutorial/custom_ui_tutorial.md
index 1f3422c..7ba5981 100644
--- a/docs/tutorial/custom_ui_tutorial.md
+++ b/docs/tutorial/custom_ui_tutorial.md
@@ -38,24 +38,24 @@ Tutorial attendees should have:
Python 3.6-3.9 are supported, but I highly recommend you download and use
**Python 3.9**
-1. Download and install Python 3.9.
- - (macOS/Windows): Download from https://www.python.org/downloads/
- - (Linux): use your distribution's package manager to install Python 3.9
-2. (macOS/Linux) Verify you have installed Python 3.9. Open a terminal and run
- `python3.9 --version`.
+Download and install Python 3.9.
-```
-$ python3.9 --version
-Python 3.9.5
-```
+- (macOS/Windows): Download from <https://www.python.org/downloads/>
+- (Linux): use your distribution's package manager to install Python 3.9
-3. (Windows) Verify you have installed Python 3.9. Open `cmd` and run
- `py --version`:
+Verify you have installed Python 3.9:
-```text
-C:\Users\machrist>py --version
-Python 3.9.5
-```
+=== "macOS/Linux"
+
+ $ python3.9 --version
+ Python 3.9.5
+
+=== "Windows"
+
+ Open `cmd` then run:
+
+ C:\Users\username>py --version
+ Python 3.9.5
## Outline
@@ -383,35 +383,35 @@ We have a local develop environment created. Now we can start adding custom
code. First, we'll create a custom Django app, which is the standard way to
package a Django extension.
-1. (macOS/Linux) Create and activate a Python virtual environment
+#### Create and activate a Python virtual environment
-```bash
-$ cd $HOME
-$ python3.9 -m venv tutorial-env
-$ source tutorial-env/bin/activate
-(tutorial-env) $
-```
+=== "macOS/Linux"
-2. (Windows) Create and activate a Python virtual environment
+ $ cd $HOME
+ $ python3.9 -m venv tutorial-env
+ $ source tutorial-env/bin/activate
+ (tutorial-env) $
-```text
-C:\Users\machrist>cd %HOMEDRIVE%%HOMEPATH%
+=== "Windows"
-C:\Users\machrist>py -m venv tutorial-env
+ C:\Users\username>cd %HOMEDRIVE%%HOMEPATH%
-C:\Users\machrist>tutorial-env\Scripts\activate.bat
+ C:\Users\username>py -m venv tutorial-env
-(tutorial-env) C:\Users\machrist>
-```
+ C:\Users\username>tutorial-env\Scripts\activate.bat
+
+ (tutorial-env) C:\Users\username>
+
+#### Run the django app cookiecutter
-3. Install the latest version of cookiecutter. Cookiecutter is a tool for
+1. Install the latest version of cookiecutter. Cookiecutter is a tool for
generating project source code from a template.
```sh
pip install -U cookiecutter
```
-4. Use cookiecutter to run the Airavata Django app template.
+2. Use cookiecutter to run the Airavata Django app template.
```sh
cookiecutter https://github.com/machristie/cookiecutter-airavata-django-app.git
@@ -431,110 +431,104 @@ version [0.1.0]:
### Setup local Django portal development environment
-To run the Django portal locally we'll start it as a Docker container. Another
-option, which we won't cover in this tutorial, is to check out the code and run
-the portal locally as a Python process (see the airavata-django-portal
-[README](https://github.com/apache/airavata-django-portal/blob/master/README.md)
-if you are interested).
+For running the local Django portal development environment, there are a few
+options:
-1. Make sure you have
- [Docker installed](https://www.docker.com/products/docker-desktop).
-2. Run the following to create a Docker container called **custom-ui-tutorial**.
+- **Docker**: Run the portal as a Docker container. If you have Docker
+ installed, this is the **recommended** option for the tutorial.
+- **Python**: Install the portal dependencies (Python and Nodejs) and then run
+ it directly on your computer. This is recommended when you don't or can't
+ have Docker installed. It is also what we recommend when you are developing
+ a real custom django app extension.
-```
-cd $HOME
-git clone https://github.com/machristie/custom_ui_tutorial_app.git custom_ui_tutorial_app-final
-cd custom_ui_tutorial_app
-docker run -d --name custom-ui-tutorial -p 8000:8000 -v "$PWD:/extensions" -v "$PWD/../custom_ui_tutorial_app-final/settings_local.py:/code/django_airavata/settings_local.py" machristie/airavata-django-portal
-```
+=== "Docker (macOS/Linux)"
-!!! note "For remote Docker host users"
+ 1. Make sure you have
+ [Docker installed](https://www.docker.com/products/docker-desktop).
+ 2. Run the following to create a Docker container called **custom-ui-tutorial**.
- If you are using a remote Docker host (for example, you have Windows Home
- and can't install Docker Desktop), make sure you run the above commands
- on the remote Docker host. That means you need to
- `ssh USERNAME@IP_ADDRESS` to the remote host first. See [Appendix on
- running on a remote Docker
- host](#appendix-setting-up-windows-for-a-remote-docker-host) for more
- information on setting up the SSH connection. You can run the remaining
- `docker` commands on your own computer, but this `docker run` command
- must be run on the remote Docker host so that the tutorial files can be
- mounted into it.
+ cd $HOME
+ git clone https://github.com/machristie/custom_ui_tutorial_app.git custom_ui_tutorial_app-final
+ cd custom_ui_tutorial_app
+ docker run -d --name custom-ui-tutorial -p 8000:8000 -v "$PWD:/extensions" -v "$PWD/../custom_ui_tutorial_app-final/settings_local.py:/code/django_airavata/settings_local.py" machristie/airavata-django-portal
+ 3. Run the following to load the default set of CMS pages:
-!!! note
+ docker exec custom-ui-tutorial python manage.py load_cms_data new_default_theme
- You can also build the Docker image from scratch, which you might want to
- do if the Docker image is out-dated. To do that run the following:
+=== "Python (Windows)"
- cd /tmp/
- git clone https://github.com/apache/airavata-django-portal.git
- cd airavata-django-portal
- docker build -t airavata-django-portal .
+ Verify that you have the following installed
- Now you can `airavata-django-portal` instead of
- `machristie/airavata-django-portal` in the `docker run` command above.
+ - Python 3.9
+ - Node LTS
+ - Yarn
+ - Git
-3. Run the following to load the default set of CMS pages:
+ The following instructions assume that you start in your home directory, but you
+ could technically checkout and build the code anywhere.
-```
-docker exec custom-ui-tutorial python manage.py load_cms_data new_default_theme
-```
+ 1. Make sure that you have activated your `tutorial-env` virtual
+ environment. You should see `(tutorial-env)` at the beginning of the CMD
+ prompt. See the [virtual environment instructions if
+ needed](#create-and-activate-a-python-virtual-environment).
-#### Python/Windows instructions
+ 2. Clone the custom_ui_tutorial_app and airavata-django-portal repositories.
-Verify that you have the following installled
+ (tutorial-env) C:\Users\username>cd %HOMEDRIVE%%HOMEPATH%
-- Python 3.9
-- Node LTS
-- Yarn
-- Git
+ (tutorial-env) C:\Users\username>git clone https://github.com/machristie/custom_ui_tutorial_app.git custom_ui_tutorial_app-final
-The following instructions assume that you start in your home directory, but you
-could technically checkout and build the code anywhere.
+ (tutorial-env) C:\Users\username>git clone https://github.com/apache/airavata-django-portal.git
-1. Clone the custom_ui_tutorial_app and airavata-django-portal repositories.
+ 3. Install the airavata-django-portal dependencies.
-```text
-(tutorial-env) C:\Users\machrist>cd %HOMEDRIVE%%HOMEPATH%
+ (tutorial-env) C:\Users\username>cd airavata-django-portal
-(tutorial-env) C:\Users\machrist>git clone https://github.com/machristie/custom_ui_tutorial_app.git custom_ui_tutorial_app-final
+ (tutorial-env) C:\Users\username\airavata-django-portal>pip install -U pip
-(tutorial-env) C:\Users\machrist>git clone https://github.com/apache/airavata-django-portal.git
-```
+ (tutorial-env) C:\Users\username\airavata-django-portal>pip install -r requirements.txt
-2. Install the airavata-django-portal dependencies.
+ 4. Copy in the settings_local.py file.
-```text
-(tutorial-env) C:\Users\machrist>cd airavata-django-portal
+ (tutorial-env) C:\Users\username\airavata-django-portal>copy ..\custom_ui_tutorial_app-final\settings_local.py django_airavata\
-(tutorial-env) C:\Users\machrist\airavata-django-portal>pip install -U pip
+ 5. Run Django database migrations
-(tutorial-env) C:\Users\machrist\airavata-django-portal>pip install -r requirements.txt
-```
+ (tutorial-env) C:\Users\username\airavata-django-portal>python manage.py migrate
-3. Copy in the settings_local.py file.
+ 6. Load the default Wagtail CMS pages.
-```text
-(tutorial-env) C:\Users\machrist\airavata-django-portal>copy ..\custom_ui_tutorial_app-final\settings_local.py django_airavata\
-```
+ (tutorial-env) C:\Users\username\airavata-django-portal>python manage.py load_cms_data new_default_theme
-4. Run Django database migrations
+ 7. Build the JavaScript frontend code.
-```text
-(tutorial-env) C:\Users\machrist\airavata-django-portal>python manage.py migrate
-```
+ (tutorial-env) C:\Users\username\airavata-django-portal>build_js.bat
-5. Load the default Wagtail CMS pages.
+!!! note "For remote Docker host users"
-```text
-(tutorial-env) C:\Users\machrist\airavata-django-portal>python manage.py load_cms_data new_default_theme
-```
+ If you are using a remote Docker host (for example, you have Windows Home
+ and can't install Docker Desktop), make sure you run the above commands
+ on the remote Docker host. That means you need to
+ `ssh USERNAME@IP_ADDRESS` to the remote host first. See [Appendix on
+ running on a remote Docker
+ host](#appendix-setting-up-windows-for-a-remote-docker-host) for more
+ information on setting up the SSH connection. You can run the remaining
+ `docker` commands on your own computer, but this `docker run` command
+ must be run on the remote Docker host so that the tutorial files can be
+ mounted into it.
-6. Build the JavaScript frontend code.
+!!! note
-```text
-(tutorial-env) C:\Users\machrist\airavata-django-portal>build_js.bat
-```
+ You can also build the Docker image from scratch, which you might want to
+ do if the Docker image is out-dated. To do that run the following:
+
+ cd /tmp/
+ git clone https://github.com/apache/airavata-django-portal.git
+ cd airavata-django-portal
+ docker build -t airavata-django-portal .
+
+ Now you can use `airavata-django-portal` instead of
+ `machristie/airavata-django-portal` in the `docker run` command above.
---
@@ -772,28 +766,24 @@ install_requires =
10. Now we need to install the _custom_ui_tutorial_app_ package into the Django
portal's virtual environment.
-Docker instructions:
+=== "Docker (macOS/Linux)"
-```bash
-docker exec -w /extensions custom-ui-tutorial pip install -e .
-docker exec custom-ui-tutorial touch /code/django_airavata/wsgi.py
-```
+ docker exec -w /extensions custom-ui-tutorial pip install -e .
+ docker exec custom-ui-tutorial touch /code/django_airavata/wsgi.py
-These commands:
+ These commands:
-1. install our custom django app package and its dependencies into the
- container's Python environment, and
-2. touches the wsgi.py to trigger a reload of the Django portal dev server.
+ 1. install our custom django app package and its dependencies into the
+ container's Python environment, and
+ 2. touches the wsgi.py to trigger a reload of the Django portal dev server.
-Python/Windows instructions:
+=== "Python (Windows)"
-```text
-(tutorial-env) C:\Users\machrist\airavata-django-portal>cd ..\custom_ui_tutorial_app
+ (tutorial-env) C:\Users\username\airavata-django-portal>cd ..\custom_ui_tutorial_app
-(tutorial-env) C:\Users\machrist\custom_ui_tutorial_app>pip install -e .
+ (tutorial-env) C:\Users\username\custom_ui_tutorial_app>pip install -e .
-(tutorial-env) C:\Users\machrist\airavata-django-portal>python manage.py runserver
-```
+ (tutorial-env) C:\Users\username\airavata-django-portal>python manage.py runserver
### Use the GaussianEigenvaluesViewProvider with the Gaussian log output file
diff --git a/mkdocs.yml b/mkdocs.yml
index 6b17256..2da4025 100644
--- a/mkdocs.yml
+++ b/mkdocs.yml
@@ -22,8 +22,12 @@ nav:
theme: readthedocs
+extra_css:
+ - assets/css/pymdownx.tabbed.css
+
markdown_extensions:
- sane_lists # allow restarting numbering of ordered lists
- admonition
- toc:
permalink: true
+ - pymdownx.tabbed
diff --git a/requirements-dev.txt b/requirements-dev.txt
index 40c56a4..36f48db 100644
--- a/requirements-dev.txt
+++ b/requirements-dev.txt
@@ -3,8 +3,9 @@ autopep8==1.5.4
flake8==3.8.4
flake8-isort==4.0.0
isort==5.2.2
-mkdocs==1.0.4
+mkdocs==1.1.2
Markdown==3.2.1
+pymdown-extensions==8.2
pycodestyle==2.6.0
pyflakes==2.2.0
tox==3.20.0