Updated the README to simplify steps for new users #51
Conversation
README.md
Outdated
| - 🐍 Python >= 3.7 | ||
| - 📔 Jupyter Notebook >= 6.2 (Doesn't support Jupyter Lab) | ||
| - Supported Python installation methods include system-level and [miniconda](https://docs.conda.io/en/latest/miniconda.html) | ||
| - [Anaconda](https://www.anaconda.com/products/distribution) support is experimental |
There was a problem hiding this comment.
I don't think you need to mention anaconda support is experimental and it only works on miniconda. This plugin has nothing to do with the environment and the problem you had was very environment specific. I just tested with anaconda in Linux and it works out of the box.
| ``` | ||
|
|
||
| **Jupynium server stays alive as long as the browser is alive.** | ||
| So you can see them as the same thing in this doc. | ||
| **Option 2**: This method requires that you have already connected to the Jupynium server: |
There was a problem hiding this comment.
You mentioned about "Jupynium server" without explaining what it is. It's in the next section that you can think of it as a selenium browser session, but I think we should mention that first at the very beginning of the Usage section
README.md
Outdated
|
|
||
| 2. Manually open the file from the browser, and `:JupyniumStartSync 2` to sync using the 2nd tab (count from 1). | ||
| If you want to save a copy of the `.ipynb` file, run `:JupyniumSaveIpynb`. There is also a configuration option to enable automatic saving/downloading. |
There was a problem hiding this comment.
:JupyniumSaveIpynb saves the notebook file from the notebook server. It will also be done automatically when you save the vim file and there's no option to turn it off yet.
If you want to keep a copy you need to use :JupyniumDownloadIpynb.
README.md
Outdated
| If you have `auto_attach_to_server = false` during setup, you need to run `:JupyniumAttachToServer` and `:JupyniumStartSync`. | ||
|
|
||
| ## 📝 .ju.py (or .ju.\*) file format | ||
| ## 👨💻️ Command-Line Usage (attach to remote Neovim) |
There was a problem hiding this comment.
Is there any reason the command line usage is in this section? Maybe it's more closely related, but this is just for advanced use cases and users shouldn't need to know for most cases, that's why I put it at the near end. I think the file format may need to come first or emphasise in this section that if you don't plan to do so just skip to the next section?
README.md
Outdated
|
|
||
| The file format is designed to be LSP friendly even with markdown code injected in it. The markdown cells will be part of python string `"""%%` ... `%%"""`. | ||
| The file format is designed to be LSP friendly even with markdown code injected into it. The markdown cells will be part of a Python docstring: `"""%%` ... `%%"""`. |
There was a problem hiding this comment.
Docstring means it's a string at the first line of a module definition. You can just say multi-line string or just leave it as string
|
Overall it looks really good! Thanks for doing this :) I think the Usage section is definitely improved, but also it got longer. I also think it may be easier to understand if they just try it out and read the rest. How about making a section like this? ## Quick Start
- Open a `*.ju.py` file.
- Execute `:JupyniumStartAndAttachToServer`. This will open Jupyter Notebook on the Firefox browser.
- If not, clarify option `jupyter_command` or just open the Notebook server by yourself: `jupyter notebook`
- Execute `:JupyniumStartSync`. This will create an `Untitled.ipynb` file on the browser.
- Now you can type `# %%` in Neovim to create a code cell.
- You'll see everything you type below that will be synchronised in the browser.
- Execute cells using the default keybind `<space>x`.
For detailed instructions, see Usage. |
README.md
Outdated
| - ✌️ Neovim >= v0.8 | ||
| - 🦊 Firefox | ||
| - Other browsers are not supported due to their limitation with Selenium |
There was a problem hiding this comment.
Let's add this reference: #49 (comment)
|
Everything you mentioned makes sense, especially the quickstart section. Added everything in the latest commit |
|
Fab! Thank you so much again! |
Addresses some of the issues discussed in #44