Merge pull request #80 from choldgraf/sphinx

blink1073 · web-flow · commit cc60f08a9910 · 2021-12-02T13:57:25.000-06:00
Convert build to a Sphinx site and minor updates to docs
diff --git a/.circleci/config.yml b/.circleci/config.yml
diff --git a/.gitignore b/.gitignore
@@ -28,3 +28,6 @@ node_modules
 
 # Jupyter Book
 _build
+
+# Python files
+__pycache__
diff --git a/47-jupyter-debugger-protocol/debugger-screencast.gif b/47-jupyter-debugger-protocol/debugger-screencast.gif
diff --git a/47-jupyter-debugger-protocol/jupyter-debugger-protocol.md b/47-jupyter-debugger-protocol/jupyter-debugger-protocol.md
@@ -1,4 +1,4 @@
-# Jupyter debugger protocol [active]
+# Jupyter debugger protocol
 
 | Item       | Value                                                                                                                        |
 |------------|------------------------------------------------------------------------------------------------------------------------------|
diff --git a/72-language-server-protocol/language-server-protocol.md b/72-language-server-protocol/language-server-protocol.md
@@ -6,7 +6,9 @@ pr-number: 72
 date-started: 2021-06-27
 ---
 
-# Summary
+# Jupyter integration with the Language Server Protocol
+
+## Summary
 
 [jupyter(lab)-lsp](https://github.com/krassowski/jupyterlab-lsp) is a project bringing integration
 of language-specific IDE features (such as diagnostics, linting, autocompletion, refactoring) to the
@@ -20,7 +22,7 @@ a working implementation, the proposal is not tied to it (beyond a proposal for
 repository to a Jupyter-managed GitHub organization) but rather aimed to guide the process of
 formalizing and evolving the way of integrating Jupyter with LSP in general.
 
-# Motivation
+## Motivation
 
 A common criticism of the Jupyter environment (regardless of the front-end editor) and of the
 official Jupyter frontends (in light of recent, experimental support of feature-rich notebook
@@ -38,7 +40,7 @@ VSCode(TM).
 Many language servers are community supported and available for free (see the community-maintained
 list of [language servers](https://langserver.org/)).
 
-# Guide-level explanation
+## Guide-level explanation
 
 Much like
 [Jupyter Kernel Messaging](https://jupyter-client.readthedocs.io/en/stable/messaging.html), LSP
@@ -59,14 +61,14 @@ line) and Jupyter Server (for the `1.x`). We will discuss the architecture and e
 of maintaining these components at greater length, leveraging a good deal of the user and developer
 [documentation](https://jupyterlab-lsp.readthedocs.io/en/latest/?badge=latest).
 
-# Reference-level explanation
+## Reference-level explanation
 
 The current implementation of the LSP integration is a barely a proof of concept. We believe that a
 different implementation should be developed to take the more comprehensive use cases and diversity
 of the Jupyter ecosystem into account; we created detailed proposals for improvement and refactoring
 of our code as explained later.
 
-## Dealing with Jupyter notebooks complexity
+### Dealing with Jupyter notebooks complexity
 
 The following features need to be considered in the design:
 
@@ -81,7 +83,7 @@ existing languages:
   warn users about unused empty cells, out of order execution markers, etc., as briefly discussed in
   [#467](https://github.com/krassowski/jupyterlab-lsp/issues/467))
 
-## Current implementation
+### Current implementation
 
 Currently:
 
@@ -102,7 +104,7 @@ Currently:
       specification of the LSP servers (where to look for an executable of the LSP server, for which
       languages/kernels given LSP server should be used, what is its display name, etc.)
 
-# Rationale and alternatives
+## Rationale and alternatives
 
 A previous (stale) JEP proposed to integrate LSP and to adopt Monaco editor, which would entail
 bringing a heavy dependency and large reliance on continuous development of Monaco by Microsoft; it
@@ -119,7 +121,7 @@ driver behind bad coding practices due to the lack of available toolset in the o
 Alternative formats to ipynb were proposed and sometimes the only motivation was a better
 IDE-features support.
 
-# Prior art
+## Prior art
 
 Multiple editors already support the Language Server Protocol, whether directly or via extension
 points, including VSCode, Atom, Brackets (Adobe), Spyder, Visual Studio and many more. The list of
@@ -136,7 +138,7 @@ The on-going integration of the [Debug Adapter Protocol][dap] has demonstrated b
 benefits, and kernel maintainer costs, of "embracing and extending" existing, non-Jupyter protocols
 rather than re-implementing.
 
-# Unresolved questions
+## Unresolved questions
 
 The current implementation can be improved by:
 
@@ -185,7 +187,7 @@ on user and/or developer experience:
 - enabling integration with other packages providing completion suggestions
 - enabling use of multiple LSP servers for a single document
 
-# Future possibilities
+## Future possibilities
 
 - Amending the kernel messaging protocol to ask only for runtime (e.g. keys in a dictionary, columns
   in a data frame) and kernel-specific completions (e.g. magics), this is excluding static-analysis
diff --git a/README.md b/README.md
@@ -33,8 +33,10 @@ encouraged to commence on the topic.
 | 0029 | **Accepted** | [Jupyter Enhancement Proposal updates](29-jep-process/jep-process.md) | [#29](https://github.com/jupyter/enhancement-proposals/pull/29) |
 | 0042 | **Accepted** | [Voila Incorporation](42-voila-incorporation/voila-incorporation.md) | [#43](https://github.com/jupyter/enhancement-proposals/pull/43) |
 | 0044 | **Accepted** | [Xeus Incorporation](44-xeus-incorporation/xeus-incorporation.md) | [#44](https://github.com/jupyter/enhancement-proposals/pull/44) |
+| 0047 | **Accepted** | [Jupyter Debugger Protocol](47-jupyter-debugger-protocol/jupyter-debugger-protocol.md) | [#47](https://github.com/jupyter/enhancement-proposals/pull/47) |
 | 0062 | **Accepted** | [Cell ID Addition to Notebook Format](62-cell-id/cell-id.md) | [#62](https://github.com/jupyter/enhancement-proposals/pull/62) |
 | 0072 | **Accepted** | [Language server protocol (LSP)](72-language-server-protocol/language-server-protocol.md) | [#72](https://github.com/jupyter/enhancement-proposals/pull/72) |
+| 0079 | **Submitted** | Build Jupyter Notebook v7 off of JupyterLab components | [#79](https://github.com/jupyter/enhancement-proposals/pull/79) |
 
 ## How do I submit a JEP?
 
@@ -44,3 +46,31 @@ In addition, read
 [the JEP proposal template](jupyter-enhancement-proposal-guidelines/JEP-TEMPLATE.md)
 for guidance on the questions you should answer before officially submitting
 the JEP.
+
+## Build the enhancement proposal docs
+
+The Enhancement Proposal documentation is structured as a [Sphinx documentation site](https://www.sphinx-doc.org/) that uses a them and configuration inspired by [Jupyter Book](https://jupyterbook.org).
+
+To build the documentation locally, use [the `nox` automation and environment management tool](https://nox.thea.codes/).
+Follow these steps:
+
+- Install `nox`:
+
+  ```console
+  $ pip install nox
+  ```
+- Build the docs from the `enhancement-proposals` folder:
+  
+  ```console
+  $ nox -s docs
+  ```
+
+This will automatically install the environment needed to build the documentation, and then place the output HTML in the `_build/html` folder.
+
+To build the documentation with a live reload server, run:
+
+```console
+$ nox -s docs-live
+```
+
+To manually install and build the documentation with Sphinx, install the requirements in `requirements.txt` and then run `sphinx-build . _build/html`.
diff --git a/_toc.yml b/_toc.yml
@@ -9,7 +9,9 @@ parts:
 
 - caption: Accepted JEPs
   chapters:
+  - file: 72-language-server-protocol/language-server-protocol.md
   - file: 62-cell-id/cell-id
+  - file: 47-jupyter-debugger-protocol/jupyter-debugger-protocol.md
   - file: 44-xeus-incorporation/xeus-incorporation
   - file: 42-voila-incorporation/voila-incorporation
   - file: 29-jep-process/jep-process
diff --git a/conf.py b/conf.py
@@ -0,0 +1,32 @@
+author = "Project Jupyter"
+copyright = "2021"
+exclude_patterns = ["_build", ".nox", ".github"]
+extensions = [
+    "myst_parser",
+    "sphinx_copybutton",
+    "sphinx_external_toc",
+    "sphinx.ext.intersphinx",
+    "sphinx_book_theme",
+]
+html_baseurl = "https://jupyter.org/enhancement-proposals"
+html_favicon = ""
+html_logo = ""
+html_sourcelink_suffix = ""
+html_theme = "sphinx_book_theme"
+html_theme_options = {
+    "search_bar_text": "Search the docs...",
+    "repository_url": "https://github.com/jupyter/enhancement-proposals",
+    "repository_branch": "master",
+    "home_page_in_toc": True,
+    "use_repository_button": True,
+    "use_edit_page_button": True,
+    "use_issues_button": True,
+}
+html_title = "Jupyter Enhancement Proposals"
+
+myst_enable_extensions = [
+    "colon_fence",
+    "linkify",
+]
+pygments_style = "sphinx"
+
diff --git a/noxfile.py b/noxfile.py
@@ -0,0 +1,26 @@
+import nox
+
+nox.options.reuse_existing_virtualenvs = True
+
+build_command = ["-b", "html", ".", "_build/html"]
+
+@nox.session
+def docs(session):
+    session.install("-r", "requirements.txt")
+    session.run("sphinx-build", *build_command)
+
+@nox.session(name="docs-live")
+def docs_live(session):
+    session.install("-r", "requirements.txt")
+    session.install("sphinx-autobuild")
+
+    AUTOBUILD_IGNORE = [
+        "_build",
+        "build_assets",
+        "tmp",
+    ]
+    cmd = ["sphinx-autobuild"]
+    for folder in AUTOBUILD_IGNORE:
+        cmd.extend(["--ignore", f"*/{folder}/*"])
+    cmd.extend(build_command)
+    session.run(*cmd)
diff --git a/requirements.txt b/requirements.txt
@@ -0,0 +1,5 @@
+linkify-it-py
+myst-parser
+sphinx-book-theme
+sphinx-copybutton
+sphinx_external_toc

Original file line number	Diff line number	Diff line change
`@@ -1,4 +1,4 @@`
`1`		`-# Jupyter debugger protocol [active]`
	`1`	`+# Jupyter debugger protocol`
`2`	`2`
`3`	`3`	`\| Item \| Value \|`
`4`	`4`	`\|------------\|------------------------------------------------------------------------------------------------------------------------------\|`