docs!: Adds doc-kill melos command and bumps requirements (#2397)

As mentioned in #2395, there are several lingering issues that can be solved by bumping the Python package requirements up. All packages need / can run on Python 3.8+, so the docs do not need to be updated regarding that.

This PR specifically fixes the following warnings:

flame\doc\bridge_packages\bridge_packages.md:4: WARNING: 'myst' reference target not found: ..\bridge_packages\flame_audio\flame_audio.md
....There were a lot of those....

`attrs_image` is deprecated.  Use `attrs_inline` instead.

Additionally, this PR adds a new command melos doc-kill which executes the kill-server.py script. This script relies on psutil which has been added to the requirements.txt, but allows a cross platform ability to isolate and kill process threads that are locking the port 8000. This commonly happens when you exit melos doc-serve and the internal web server doesn't die as well. This may not be an issue for Unix platforms, but for Windows users its extremely annoying.

The only alternative for Windows users is to manually do:

netstat -ano | findstr :8000
// Then run:
taskkill /PID XXXXX /F 

As I mentioned in the other PR, I split this out so it can be debated mainly for the bump in requirements; however, I feel the benefits are very worth it. I marked this as breaking just because it changes the base package requirements and adds a package which may not qualify as breaking, depending on how you look at it.

Edit: Forgot that this PR also fixes a typo in the melos doc-serve description and corrects the misspelling of everytime to every time.

doc/_sphinx/conf.py

@@ -41,7 +41,7 @@
 # Configuration options for MyST:
 # https://myst-parser.readthedocs.io/en/latest/syntax/optional.html
 myst_enable_extensions = [
- 'attrs_image',
+ 'attrs_inline',
  'colon_fence',
  'deflist',
  'dollarmath',

doc/_sphinx/kill-server.py

@@ -0,0 +1,7 @@
+from psutil import process_iter
+from signal import SIGTERM # or SIGKILL
+
+for proc in process_iter():
+ for conns in proc.connections(kind='inet'):
+ if conns.laddr.port == 8000:
+ proc.send_signal(SIGTERM) # or SIGKILL

doc/_sphinx/requirements.txt

@@ -1,7 +1,8 @@
 linkify-it-py==2.0.0
-myst-parser==0.18.1
-Pygments==2.12.0
-Sphinx==5.0.2
+myst-parser==1.0.0
+Pygments==2.14.0
+Sphinx==6.1.3
 sphinxcontrib-mermaid==0.8.1
 sphinx-autobuild==2021.3.14
-jinja2==3.1.2
+Jinja2==3.1.2
+psutil==5.9.4

doc/development/documentation.md

@@ -211,6 +211,7 @@ There are other make commands that you may find occasionally useful too:
 - **melos doc-clean** removes all cached generated files (in case the system gets stuck in a bad
 state).
 - **melos doc-linkcheck** to check whether there are any broken links in the documentation.
+- **melos doc-kill** removes any orphaned TCP threads running on port 8000.
 
 The generated html files will be in the `doc/_build/html` directory, you can view them directly
 by opening the file `doc/_build/html/index.html` in your browser. The only drawback is that the

melos.yaml

@@ -65,7 +65,11 @@ scripts:
 
  doc-serve:
  run: cd "$MELOS_ROOT_PATH/doc/_sphinx" && make livehtml
- description: Recompiles the docs enerytime there is a change in them and opens your browser.
+ description: Recompiles the docs every time there is a change in them and opens your browser.
+
+ doc-kill:
+ run: cd "$MELOS_ROOT_PATH/doc/_sphinx" && python kill-server.py
+ description: Kills any TCP processes running on port 8000.
 
  doc-clean:
  run: cd "$MELOS_ROOT_PATH/doc/_sphinx" && make clean