PR - Documentation and BRAT support

beta-manifest.json

@@ -0,0 +1,10 @@
+{
+	"id": "jupyter",
+	"name": "Jupyter",
+	"version": "0.2.0-beta",
+	"minAppVersion": "0.15.0",
+	"description": "Open .ipynb files with Jupyter in Obsidian.",
+	"author": "Maël Imhof",
+	"authorUrl": "https://www.mael.im",
+	"isDesktopOnly": true
+}

docs/content/discover.md

@@ -0,0 +1,40 @@
+---
+title: Discover the plugin's features
+---
+Jupyter for Obsidian is a simple plugin and does basically two things:
+
+1. Run a Jupyter server for you (instead of opening a terminal and typing `jupyter [...]`)
+2. Tell Obsidian how to open `.ipynb` files
+
+This is a very minimal plugin, hence I'm interested in your [[index#Providing Feedback|feedback]] to build from here.
+## Starting Jupyter
+
+Opening `.ipynb` files inside of Obsidian still requires you to start a Jupyter server. Good news, the plugin can handle this for you.
+
+There are three ways for you to start a Jupyter server:
+
+1. Simply open a `.ipynb` file. By default, the plugin is [[settings#Start Jupyter automatically|configured]] to automatically run Jupyter before opening the file.
+2. Use the ribbon icon, unless you have [[settings#Display ribbon icon|disabled it]].
+3. Navigate to the settings of the plugin and use the [[settings#Server running|Server running]] setting to toggle the state of the Jupyter server.
+## Configuring Jupyter
+### Choosing Between Lab and Notebook
+
+You can open your `.ipynb` files using either Jupyter Lab or Jupyter Notebook, depending on your preferences. You can change this behaviour using the setting [[settings#Jupyter environment type|Jupyter environment type]].
+### Choosing the Python Executable
+
+By default, the plugin will use a simply `python` shell command to run Jupyter. However, if you installed Jupyter in a Python virtual environment or with Conda/Miniconda, you'll want to change the Python executable.
+
+You can do so by changing the setting [[settings#Python executable path|Python executable path]]. If you want to use an executable path instead of the `python` command, you must also ensure that [[settings#Python executable to use|Python executable to use]] is set to `Specified executable path`, otherwise the `python` command will still be used.
+
+In particular, if you use Conda or Miniconda, see [[miniconda-and-conda|this guide]] to find the executable path you should use.
+## Toggle Ribbon and Status Notices
+
+By default, the plugin will show a ribbon icon allowing you to start and stop the Jupyter server in one click.
+
+![[ribbon-icon.png]]
+
+It will also display status notices to tell you how the server is doing. One will be displayed when the server is starting, running or has exited.
+
+![[status-notices.png]]
+
+You can disable both [[settings#Display ribbon icon|the ribbon icon]] and [[settings#Display status notices|the status notices]] individually using the two corresponding settings, if you do not find them necessary.

docs/content/index.md

@@ -1,5 +1,39 @@
 ---
-title: Jupyter for Obsidian
+title: Beta-testers, read this
 ---
+Hi !
 
-Hello there !
+Want to transparently open `.ipynb` files in Obsidian? Run your Jupyter notebooks directly inside Obsidian? You're at the right place!
+
+![[jupyter-inside-obsidian.png]]
+
+## Entering Beta
+
+This Obsidian plugin is entering beta now. I want to gather feedback and improve it if necessary before releasing it as an Obsidian community plugin.
+
+- **The plugin should already be working.**
+
+  You can open `.ipynb` files, run a Jupyter server, tweak the parameters to adapt the plugin for your use case.
+- **Some bugs might have gone unnoticed until now.**
+
+  Although I tested the plugin thoroughly myself, it might behave unexpectedly on different environments, that's why I need beta testers to see if it works for them as well.
+- **Please give me feedback.**
+
+  Tell me what you like, what you don't, what you *would* like, anything. I'll see what I can do.
+
+## Installing the plugin
+
+> [!TODO] Do this installing plugin with BRAT section
+## Providing Feedback
+
+Once the plugin is installed, you can start using it normally in your Obsidian vault. Discover the [[discover|features of the plugin]] and try playing a bit with it, see how it integrates with your workflow.
+
+Please send me feedback about your experience with the plugin! This would help me a lot improving and releasing it in the official list of Obsidian community plugins.
+
+To share feedback, choose between the following, depending on your preference and convenience.
+
+- Participate on [this **Obsidian forum** post](https://forum.obsidian.md/t/jupyter-notebook-integration-for-obsidian/4951/40), I'll be monitoring new comments.
+- Open an [**issue on GitHub**](https://github.com/MaelImhof/obsidian-jupyter/issues), choose an issue template as you wish. Beta feedback has only one field to fill in though, so it might be quicker.
+- Join the [**Discord** server](https://discord.gg/KgkwwRJ3mQ) I quickly put together for the occasion.
+
+Thank you in advance for your time, I hope you'll like the plugin!

docs/content/miniconda-and-conda.md

@@ -0,0 +1,18 @@
+---
+title: Run from Conda or Miniconda
+---
+If you installed Python with Conda or Miniconda, you will need to configure the plugin accordingly before being able to use it.
+## Find Python Executable
+
+First, you'll need to find the Python executable path of the Conda environment you want to use (most likely the environment where you installed Jupyter).
+
+Use the instructions provided by the [Anaconda documentation](https://docs.anaconda.com/free/working-with-conda/configurations/python-path/) and copy the executable path that it gives you.
+## Configure the Plugin
+
+Once you have the right Python executable path, paste it as the value of the [[settings#Python executable path|Python executable path]] setting. This will tell the plugin that Python has to be run from this place.
+
+Also set [[settings#Python executable to use|Python executable to use]] to `Specified executable path` so that the path you used above is taken into consideration by the plugin.
+
+And voilà ! You should be able to run your Jupyter environment from Conda or Miniconda.
+
+If you encounter any problem, please see the [[troubleshooting|troubleshooting guide]].

docs/content/settings.md

@@ -1,5 +1,66 @@
 ---
 title: Settings
 ---
-> [!TODO] Document existing settings
+You can configure several aspects of the plugin such as the Python executable to start Jupyter or whether or not to display a ribbon icon.
 
+A rundown of all the settings is available here.
+## Available Settings
+### Python
+#### Python executable to use
+
+Whether to use the simple `python` command to start Jupyter, or a particular Python executable file.
+
+If set to `Specified executable path`, the [[#Python executable path]] setting will be used.
+
+Set to `python` by default.
+#### Python executable path
+
+The Python executable path to use to start Jupyter. This setting has no effect if [[#Python executable to use]] is set to `python`.
+
+Empty by default.
+### Jupyter
+#### Server running
+
+Not a setting properly speaking, this toggle indicates the state of the server. If the server is starting or running, the toggle is `on`. If the server has exited or has not been started, the toggle is `off`.
+#### Start Jupyter automatically
+
+Whether to automatically start the Jupyter server when a `.ipynb` file is opened if Jupyter is not running.
+
+Default value is yes.
+#### Jupyter environment type
+
+Whether to use Jupyter Lab or Jupyter Notebook.
+
+Note that if the Jupyter server is running while you change this setting, you will need to stop it and start it again for the new value to take effect.
+
+Default value is Jupyter Lab.
+### Plugin customization
+#### Display ribbon icon
+
+Whether to display the plugin's ribbon icon or not. Can help if you find the ribbon icon unnecessary and want to get rid of it.
+
+![[ribbon-icon.png]]
+
+Default value is yes (the ribbon icon is displayed).
+#### Display status notices
+
+Whether to display status notices when the Jupyter server state updates. A notice will appear every time the server is started, running, or exits. 
+
+![[status-notices.png]]
+
+Default value is yes (the status notices are displayed).
+### Advanced
+#### Jupyter starting timeout
+
+Number of seconds to wait before Jupyter is considered to time out in the starting state. If Jupyter takes too long to get ready, it will be shutdown and an error will be displayed.
+
+This setting is to avoid Jupyter staying in the starting state for too long. Please note that making this setting too low might prevent Jupyter to even have the time to start at all.
+
+Default value is 30 seconds.
+#### Print Jupyter output to Obsidian console
+
+Whether to print what Jupyter prints to the Obsidian console.
+
+When Jupyter is started from a terminal, it prints many setup and log messages, which can be interesting for debugging, understanding a problem, or get the Jupyter URL and token to access it in a browser. This setting allows you to print all of those messages to the [Obsidian console](https://help.obsidian.md/Help+and+support#Capture+console+logs).
+
+Default value is no (nothing will be printed).

docs/content/troubleshooting.md

@@ -0,0 +1,43 @@
+---
+title: Troubleshooting
+---
+Here is a quick guide on possible fixes you can try to fix existing errors before asking for help.
+
+- [[#Existing Errors Codes]]
+	- [[#Jupyter process could not be spawned]]
+	- [[#Jupyter process crashed]]
+	- [[#Jupyter Timeout]]
+- [[#Opening a Ticket]]
+## Existing Errors Codes
+### Jupyter process could not be spawned
+
+Indicates that at the instant Jupyter is run, a problem occurs and Jupyter either never starts or crashes instantly.
+
+1. Check the provided [[settings#Python executable to use|Python executable to use]] is valid and that the [[settings#Python executable path|path]] is set correctly if not using `python`.
+2. Check that Jupyter is installed in the provided Python environment. Depending on your [[settings#Jupyter environment type|Jupyter environment type]], you will want to check Jupyter Lab or Jupyter Notebook in particular. You can do this using the command `[python_executable] -m [notebook or jupyterlab]` and see if Jupyter starts normally.
+
+If both Python and the right Jupyter environment are installed, please [[#Opening a Ticket|open a ticket]].
+### Jupyter process crashed
+
+Indicates that Jupyter was started but then crashed before being fully ready to open `.ipynb`.
+
+1. Check that Jupyter is installed in the provided Python environment. Depending on your [[settings#Jupyter environment type|Jupyter environment type]], you will want to check Jupyter Lab or Jupyter Notebook in particular. You can do this using the command `[python_executable] -m [notebook or jupyterlab]` and see if Jupyter starts normally.
+
+If the right Jupyter environment is installed, please [[#Opening a Ticket|open a ticket]].
+### Jupyter Timeout
+
+Indicates Jupyter was started and worked in the background for too long, thus it was considered that something was wrong.
+
+1. Check the value of your [[settings#Jupyter starting timeout|Jupyter starting timeout]] and try to increase it. This defines for how long to wait before considering Jupyter to be timing out. If set too low, this can prevent Jupyter from ever starting.
+
+If increasing the Jupyter starting timeout to the maximum possible value does not work for you, please run Jupyter manually from the terminal, record how long it takes from the moment you enter the command to the moment Jupyter opens your browser. Then [[#Opening a Ticket|open a ticket]] where you indicate the measured time.
+## Opening a Ticket
+
+If none of the fixes above work for you, you can request help using
+
+- [**GitHub issues**](https://github.com/MaelImhof/obsidian-jupyter/issues)
+  Choose the issue template that seems appropriate to you. By default you'll want to use **Ask for help**.
+- [**Discord server**](https://discord.gg/KgkwwRJ3mQ)
+  Join the Discord server and ask your questions in the home channel.
+
+Your feedback and bug reports will help improve the plugin, thank you !

docs/quartz.layout.ts

@@ -7,8 +7,11 @@ export const sharedPageComponents: SharedLayout = {
   header: [],
   footer: Component.Footer({
     links: {
+      Troubleshooting: "/troubleshooting",
       GitHub: "https://github.com/MaelImhof/obsidian-jupyter",
-      Issues: "https://github.com/MaelImhof/obsidian-jupyter/issues/"
+      Issues: "https://github.com/MaelImhof/obsidian-jupyter/issues/",
+      Discord: "https://discord.gg/KgkwwRJ3mQ",
+      "Obsidian Forum": "https://forum.obsidian.md/t/jupyter-notebook-integration-for-obsidian/4951/40"
     },
   }),
 }

src/jupyter-obsidian.ts

@@ -146,7 +146,7 @@ export default class JupyterNotebookPlugin extends Plugin {
 				[
 					{
 						text: "Open troubleshooting guide",
-						onClick: () => { window.open("https://github.com/MaelImhof/obsidian-jupyter/issues/", "_blank"); },
+						onClick: () => { window.open("https://jupyter.mael.im/troubleshooting#jupyter-timeout", "_blank"); },
 						closeOnClick: false
 					}
 				]
@@ -165,7 +165,7 @@ export default class JupyterNotebookPlugin extends Plugin {
 				[
 					{
 						text: "Open troubleshooting guide",
-						onClick: () => { window.open("https://github.com/MaelImhof/obsidian-jupyter/issues/", "_blank"); },
+						onClick: () => { window.open("https://jupyter.mael.im/troubleshooting#" + (error === JupyterEnvironmentError.UNABLE_TO_START_JUPYTER ? "jupyter-process-could-not-be-spawned" : "jupyter-process-crashed"), "_blank"); },
 						closeOnClick: false
 					}
 				]