|
1 | 1 | # lecture-julia.myst |
2 | | -Myst Version of lecture-source-jl |
| 2 | + |
| 3 | +Source for julia.quantecon.org |
| 4 | + |
| 5 | +## Local Development |
| 6 | + |
| 7 | +### Setup |
| 8 | + |
| 9 | +1. Download and install [Julia 1.6](https://julialang.org/downloads). |
| 10 | + |
| 11 | +2. Install [`conda`](https://www.anaconda.com/products/individual) |
| 12 | + - See [Conda Installation](https://datascience.quantecon.org/introduction/local_install.html#installation) for examples |
| 13 | + - Add conda to path |
| 14 | + |
| 15 | +3. Install [vscode](https://code.visualstudio.com/) and accept defaults if possible: |
| 16 | + - Some highly recommended packages. After installation of vscode, you should be able to click `Install` link on the webpage of any extensions |
| 17 | + - [MyST-Markdown](https://github.com/executablebooks/myst-vs-code) |
| 18 | + - [Julia](https://marketplace.visualstudio.com/items?itemName=julialang.language-julia) |
| 19 | + - Other optional, but recommended extensions |
| 20 | + - [Live Preview](https://marketplace.visualstudio.com/items?itemName=ms-vscode.live-server) |
| 21 | + - [Github Support](https://marketplace.visualstudio.com/items?itemName=GitHub.vscode-pull-request-github) |
| 22 | + - [Jupyter](https://marketplace.visualstudio.com/items?itemName=ms-toolsai.jupyter) |
| 23 | + - [Editing Markdown](https://marketplace.visualstudio.com/items?itemName=yzhang.markdown-all-in-one) |
| 24 | + - [Extra Git Tools](https://marketplace.visualstudio.com/items?itemName=eamodio.gitlens) |
| 25 | + - [Spell Checking](https://marketplace.visualstudio.com/items?itemName=streetsidesoftware.code-spell-checker) |
| 26 | + - [YAML support](https://marketplace.visualstudio.com/items?itemName=redhat.vscode-yaml) |
| 27 | + |
| 28 | + - Go to settings with `<Ctrl-Shift-P>` and search for the following settings to change: |
| 29 | + - `files.eol` to `\n` |
| 30 | + - `enablePreviewFromQuickOpen` to turn it off |
| 31 | + - `Tab Size` to `4` |
| 32 | + |
| 33 | +4. If on Windows, install [git](https://git-scm.com/downloads) and run the following in a terminal |
| 34 | + |
| 35 | + ```bash |
| 36 | + git config --global core.eol lf |
| 37 | + git config --global core.autocrlf false |
| 38 | + ``` |
| 39 | + |
| 40 | +5. Clone this repository (in vscode, you can use `<Ctrl-Shift-P>` then `Clone` then `Clone from GitHub` then choose the repo as `https://github.com/QuantEcon/lecture-julia.myst`). Or with github desktop, choose the `<> Code` dropdown on this website |
| 41 | + |
| 42 | +6. Open this repository in vscode, either from Github Desktop with `<Ctrl-Shift-A>` or with `code .` in the right folder in a terminal |
| 43 | + - After opening this repo, any terminals start at its root. |
| 44 | + |
| 45 | +7. Start a vscode terminal with ``<Ctrl+`>`` or through any other method. Create a conda environment. |
| 46 | +
|
| 47 | + ```bash |
| 48 | + conda create -n lecture-julia.myst python=3.8 |
| 49 | + conda activate lecture-julia.myst |
| 50 | + pip install -r requirements.txt |
| 51 | + ``` |
| 52 | + |
| 53 | + This will install all the jupyterbook packages required to edit and build the lectures. |
| 54 | + |
| 55 | +8. Set the default interpreter for vscode's python to be the conda env |
| 56 | + - Go `<Ctrl-Shift-P>` then `Python: Select Interpreter` |
| 57 | + - Then choose the interpeter with `lecture-julia.myst` which should now be automatically activated in the terminal. |
| 58 | + - If the interpreter does not show up in the drop-down, close and reopen vscode, then try again. Alternatively, you can run this step at the end of the setup process. |
| 59 | + - Whenever reopening vscode, re-run `conda activate lecture-julia.myst` to ensure the environment remains active. |
| 60 | +
|
| 61 | +9. Install general julia packages if not already installed. |
| 62 | +
|
| 63 | + ```bash |
| 64 | + julia -e 'using Pkg; Pkg.add("IJulia");' |
| 65 | + ``` |
| 66 | + |
| 67 | + On Windows, you should run the following instead to avoid a quoting issue: |
| 68 | + |
| 69 | + ```bash |
| 70 | + julia -e "using Pkg; Pkg.add(\"IJulia\");" |
| 71 | + ``` |
| 72 | + |
| 73 | + If the terminal responds with `'Julia' is not recognized`, close and reopen vscode, then try again. Make sure to re-activate the environment. |
| 74 | +
|
| 75 | +10. Install Julia packages required for lecture notes. |
| 76 | +
|
| 77 | + ```bash |
| 78 | + julia --project=lectures --threads auto -e 'using Pkg; Pkg.instantiate();' |
| 79 | + ``` |
| 80 | + |
| 81 | + On Windows, run the following instead: |
| 82 | + |
| 83 | + ```bash |
| 84 | + julia --project=lectures --threads auto -e "using Pkg; Pkg.instantiate();" |
| 85 | + ``` |
| 86 | +
|
| 87 | +**(Optional) REPL Integration** |
| 88 | +With [MyST-Markdown](https://github.com/executablebooks/myst-vs-code) and [Julia](https://marketplace.visualstudio.com/items?itemName=julialang.language-julia) installed, you can ensure that `<Ctrl-Enter>` on lines of code are sent to a Julia REPL. |
| 89 | +1. Open Key Bindings with `<Ctrl-K Ctrl-S>` |
| 90 | +2. Search for the `Julia: Send Current Line or Selection to REPL` binding |
| 91 | +3. Right Click on the key binding with `juliamarkdown` on it, and choose `Change When Expression`, and change `juliamarkdown` to just `markdown` |
| 92 | +
|
| 93 | +## Executing Code in Markdown Files |
| 94 | +If you installed the REPL Integration above, then in a `.md` file, |
| 95 | +
|
| 96 | +1. Start a Julia REPL with `> Julia: Start REPL` |
| 97 | +2. Activate the project file in the REPL with `] activate lectures` |
| 98 | +3. Then, assuming that you setup the keybindings above, you can send a line of code in the markdown to the REPL with `<Ctrl-Enter>` |
| 99 | +
|
| 100 | +Code can be executed line by line, or you can select a chunk of code and |
| 101 | +## Example Operations |
| 102 | +### Building the lectures |
| 103 | +To do a full build of the lectures: |
| 104 | +
|
| 105 | +```bash |
| 106 | +jupyter-book build lectures |
| 107 | +``` |
| 108 | +
|
| 109 | +or |
| 110 | +
|
| 111 | +```bash |
| 112 | +jb build lectures |
| 113 | +``` |
| 114 | +
|
| 115 | +This will take a while. But it will populate your cache, so future iteration is faster. |
| 116 | +
|
| 117 | +On Windows, if you get the following error: |
| 118 | +
|
| 119 | +``` |
| 120 | +ImportError: DLL load failed while importing win32api: The specified procedure could not be found. |
| 121 | +``` |
| 122 | +
|
| 123 | +then run `conda install pywin32` and build the lectures again. |
| 124 | +
|
| 125 | +If you have [Live Preview](https://marketplace.visualstudio.com/items?itemName=ms-vscode.live-server) installed, then go to `_build/html/index.html` in the explorer, and right-click to choose `Live Preview: Show Preview` |
| 126 | +
|
| 127 | +### Cleaning Lectures |
| 128 | +To clean up (i.e., delete the build) |
| 129 | +
|
| 130 | +```bash |
| 131 | +jupyter-book clean lectures |
| 132 | +``` |
| 133 | +
|
| 134 | +or |
| 135 | +
|
| 136 | +```bash |
| 137 | +jb clean lectures |
| 138 | +``` |
| 139 | +
|
| 140 | +to clean the `execution` cache you can use |
| 141 | +
|
| 142 | +```bash |
| 143 | +jb clean lectures --all |
| 144 | +``` |
| 145 | +### Debugging Generated Content |
| 146 | +
|
| 147 | +After execution, you can find the generated `.ipynb` and `.jl` files in `_build/jupyter_execute` for each lecture. |
| 148 | +- To see errors, you can open these in jupyterlab, the Jupyter support within VSCode, etc. |
| 149 | +- If using the Julia REPL in VS Code, make sure to do `] activate lectures` prior to testing to ensure the packages are activated. This is not necessary when opening in Jupyter. |
| 150 | +- Finally, the code is written using interactive scoping, so `include(_build/jupyter_execute/dynamic_programming/mccall_model.jl)` etc. may not work. However, `shift-enter` within VS Code to the REPL will work, and you can execute these with [SoftGlobalScope.jl](https://github.com/stevengj/SoftGlobalScope.jl) if strictly required. |
0 commit comments