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 <[email protected]> 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
