github: add workflow for publishing ide-docs package

doc/ide: add node package
This will be used to publish the docs in a way that is easy for pybricks-code to use.
2026-07-28 12:16:57 +00:00 · 2021-01-25 20:50:02 -06:00 · 2021-01-25 20:50:02 -06:00 · 2021-01-25 20:48:08 -06:00 · 2021-01-25 20:36:22 -06:00 · 2021-01-25 20:24:46 -06:00
18 changed files with 151 additions and 18 deletions
@@ -0,0 +1,38 @@
+name: Release @pybricks/ide-docs
+
+on:
+  push:
+    tags: 
+    - '@pybricks/ide-docs/**'
+
+jobs:
+  publish_ide_docs:
+    runs-on: ubuntu-20.04
+    steps:
+    - name: Ubuntu packages
+      run: |
+        sudo apt-get update
+        sudo apt-get install -y dvisvgm preview-latex-style texlive texlive-fonts-extra texlive-latex-extra
+    - uses: actions/checkout@v2
+      with:
+        submodules: recursive
+    - name: Set up Python 3.8
+      uses: actions/setup-python@v1
+      with:
+        python-version: 3.8
+    - name: Install dependencies
+      run: |
+        pip install poetry
+        poetry run python -m pip install --upgrade pip
+        poetry run python -m pip install --upgrade setuptools
+        poetry install
+    - uses: actions/setup-node@v1
+      with:
+        node-version: '14.x'
+        registry-url: 'https://registry.npmjs.org'
+    - run: yarn build
+      working-directory: doc/ide
+    - run: yarn publish
+      working-directory: doc/ide
+      env:
+        NODE_AUTH_TOKEN: ${{ secrets.NODE_AUTH_TOKEN }}
@@ -8,7 +8,7 @@ on: [ push, pull_request ]
 jobs:
  build:

-    runs-on: ubuntu-latest
+    runs-on: ubuntu-20.04
    strategy:
      matrix:
        python-version: [3.8, 3.9]
@@ -35,5 +35,9 @@ jobs:
      run: poetry run doc8
    - name: Build html docs for Read the Docs
      run: poetry run make -C doc html
+    - name: Instal IDE docs dependencies
+      run: |
+        sudo apt-get update
+        sudo apt-get install dvisvgm preview-latex-style texlive texlive-fonts-extra texlive-latex-extra
    - name: Build html docs for Pybricks Code IDE
      run: poetry run make -C doc html SOURCEDIR=ide
@@ -248,9 +248,9 @@ temperature: °C
 Temperature is measured in degrees Celcius (°C). To convert to degrees
 Fahrenheit (°F) or Kelvin (K), you can use the following conversion formulas:

-    :math:`°\!F = °\!C \cdot \frac{9}{5} + 32`.
+    :math:`^{\circ}\kern1pt\!F =\kern1pt^{\circ}\kern1pt\!C \cdot \frac{9}{5} + 32`.

-    :math:`K = °\!C + 273.15`.
+    :math:`K =\kern1pt^{\circ}\kern1pt\!C + 273.15`.

 .. _hue:

@@ -0,0 +1,6 @@
+
+/* These styles only apply to the ide build */
+
+.wy-breadcrumbs li.wy-breadcrumbs-aside {
+    display: none;
+}
@@ -35,3 +35,9 @@ span.caption-number:after {
    font-size: 60%;
    margin: 0 0.2em;
 }
+
+/* don't show external link on figures */
+/* https://github.com/readthedocs/sphinx_rtd_theme/pull/494#issuecomment-354063112 */
+.figure > a.reference.external::after {
+    content: none !important;
+}
@@ -0,0 +1,4 @@
+// https://stackoverflow.com/a/62742435/1976323
+$(document).ready(function () {
+    $('a[href^="http://"], a[href^="https://"]').not('a[class*=internal]').attr('target', '_blank');
+});
@@ -1,5 +1,5 @@
 {% extends '!footer.html' %}

 {% block extrafooter %}
-<div class="disclaimer">{{ disclaimer }}</div>
+{% if disclaimer %}<div class="disclaimer">{{ disclaimer }}</div>{% endif %}
 {% endblock %}
@@ -143,6 +143,11 @@ else:
    html_theme = 'sphinx_rtd_theme'
    html_theme_path = [sphinx_rtd_theme.get_html_theme_path()]

+# a little extra javascript
+html_js_files = [
+    'js/custom.js'
+]
+
 html_context = {
    'disclaimer': _DISCLAIMER,
 }
@@ -0,0 +1,2 @@
+version-tag-prefix "@pybricks/ide-docs/v"
+version-git-message "@pybricks/ide-docs v%s"
@@ -0,0 +1,5 @@
+
+# 1.0.0 - 2021-01-25
+
+## Added:
+- Sphinx build output.
@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2018-2021 The Pybricks Authors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
@@ -0,0 +1,6 @@
+# @pybricks/ide-docs
+
+This is a Node.js package for distributing the version of the Pybricks API
+docs that is embedded in IDEs.
+
+It contains all of the files needed to serve a static web site.
@@ -11,12 +11,22 @@ copyright = '2018-2021 The Pybricks Authors'
 author = ''

 _TITLE = 'Pybricks Modules and Examples'
-_DISCLAIMER = 'LEGO, the LEGO logo, MINDSTORMS and the MINDSTORMS EV3 logo are\
-               trademarks and/or copyrights of the LEGO Group of companies \
-               which does not sponsor, authorize or endorse this site.'
+_DISCLAIMER = ''

 html_favicon = '../common/images/favicon.ico'
 html_logo = '../common/images/pybricks-logo-rtd.png'
-latex_logo = '../common/images/pybricks-logo-large.png'
+html_show_copyright = False
+html_show_sphinx = False
+html_css_files = ['css/ide.css']
+
+imgmath_image_format = 'svg'
+imgmath_use_preview = True  # requires Sphinx v3
+imgmath_latex_preamble = r'''
+\usepackage{newtxsf}
+'''

 exec(open(os.path.abspath("../common/conf.py")).read())
+
+extensions.remove('sphinx.ext.mathjax')  # noqa F821
+extensions.append('sphinx.ext.imgmath')  # noqa F821
+html_theme_options['prev_next_buttons_location'] = None  # noqa F821
@@ -0,0 +1,24 @@
+{
+  "name": "@pybricks/ide-docs",
+  "version": "1.0.0",
+  "description": "Special build of Pybricks API docs for embedding in an IDE.",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/pybricks/pybricks-api",
+    "directory": "doc/ide"
+  },
+  "publishConfig": {
+      "registry": "https://registry.npmjs.org",
+      "access": "public"
+  },
+  "author": "The Pybricks Authors",
+  "license": "MIT",
+  "files": [
+    "build/html/**"
+  ],
+  "types": "index.d.ts",
+  "scripts": {
+    "clean": "poetry run make -C .. SOURCEDIR=ide clean",
+    "build": "poetry run make -C .. SOURCEDIR=ide html"
+  }
+}
@@ -284,15 +284,15 @@ python-versions = ">=2.7, !=3.0.*, !=3.1.*, !=3.2.*"

 [[package]]
 name = "snowballstemmer"
-version = "2.0.0"
-description = "This package provides 26 stemmers for 25 languages generated from Snowball algorithms."
+version = "2.1.0"
+description = "This package provides 29 stemmers for 28 languages generated from Snowball algorithms."
 category = "dev"
 optional = false
 python-versions = "*"

 [[package]]
 name = "sphinx"
-version = "1.7.9"
+version = "1.8.5"
 description = "Python documentation generator"
 category = "dev"
 optional = false
@@ -405,7 +405,7 @@ socks = ["PySocks (>=1.5.6,<1.5.7 || >1.5.7,<2.0)"]
 [metadata]
 lock-version = "1.1"
 python-versions = "^3.8"
-content-hash = "fed1de01e5e5b8a4350a07325982ee7dc3cca79e5e45029735ce104b29a5da55"
+content-hash = "383f496c8938184431ac13f3086cc28e4601e4f07b121dc98ff1f1752ed0cf11"

 [metadata.files]
 alabaster = [
@@ -421,6 +421,7 @@ babel = [
    {file = "Babel-2.9.0.tar.gz", hash = "sha256:da031ab54472314f210b0adcff1588ee5d1d1d0ba4dbd07b94dba82bde791e05"},
 ]
 black = [
+    {file = "black-20.8b1-py3-none-any.whl", hash = "sha256:70b62ef1527c950db59062cda342ea224d772abdf6adc58b86a45421bab20a6b"},
    {file = "black-20.8b1.tar.gz", hash = "sha256:1c02557aa099101b9d21496f8a914e9ed2222ef70336404eeeac8edba836fbea"},
 ]
 certifi = [
@@ -593,12 +594,12 @@ six = [
    {file = "six-1.15.0.tar.gz", hash = "sha256:30639c035cdb23534cd4aa2dd52c3bf48f06e5f4a941509c8bafd8ce11080259"},
 ]
 snowballstemmer = [
-    {file = "snowballstemmer-2.0.0-py2.py3-none-any.whl", hash = "sha256:209f257d7533fdb3cb73bdbd24f436239ca3b2fa67d56f6ff88e86be08cc5ef0"},
-    {file = "snowballstemmer-2.0.0.tar.gz", hash = "sha256:df3bac3df4c2c01363f3dd2cfa78cce2840a79b9f1c2d2de9ce8d31683992f52"},
+    {file = "snowballstemmer-2.1.0-py2.py3-none-any.whl", hash = "sha256:b51b447bea85f9968c13b650126a888aabd4cb4463fca868ec596826325dedc2"},
+    {file = "snowballstemmer-2.1.0.tar.gz", hash = "sha256:e997baa4f2e9139951b6f4c631bad912dfd3c792467e2f03d7239464af90e914"},
 ]
 sphinx = [
-    {file = "Sphinx-1.7.9-py2.py3-none-any.whl", hash = "sha256:a602513f385f1d5785ff1ca420d9c7eb1a1b63381733b2f0ea8188a391314a86"},
-    {file = "Sphinx-1.7.9.tar.gz", hash = "sha256:217a7705adcb573da5bbe1e0f5cab4fa0bd89fd9342c9159121746f593c2d5a4"},
+    {file = "Sphinx-1.8.5-py2.py3-none-any.whl", hash = "sha256:9f3e17c64b34afc653d7c5ec95766e03043cc6d80b0de224f59b6b6e19d37c3c"},
+    {file = "Sphinx-1.8.5.tar.gz", hash = "sha256:c7658aab75c920288a8cf6f09f244c6cfdae30d82d803ac1634d9f223a80ca08"},
 ]
 sphinx-rtd-theme = [
    {file = "sphinx_rtd_theme-0.4.3-py2.py3-none-any.whl", hash = "sha256:00cf895504a7895ee433807c62094cf1e95f065843bf3acd17037c3e9a2becd4"},
@@ -22,7 +22,7 @@ python = "^3.8"
 black = {version = "^20.8b1", allow-prereleases = true}
 doc8 = "*"
 flake8 = "*"
-sphinx = "==1.7.9"
+sphinx = "==1.8.5"
 sphinx-rtd-theme = "==0.4.3"
 toml = "^0.10.0"

@@ -1,5 +1,5 @@
 # This file is strictly for building docs on readthedocs.org
 # See pyproject.toml for local development
-Sphinx==1.7.9
+Sphinx==1.8.5
 sphinx-rtd-theme==0.4.3
 toml
@@ -5,3 +5,4 @@ max-line-length = 88

 [doc8]
 ignore-path = .venv/,doc/api/build/,pybricks.egg-info/
+max-line-length = 88
Author	SHA1	Message	Date
David Lechner	7c232362e8	github: add workflow for publishing ide-docs package	2021-01-25 20:50:02 -06:00
David Lechner	3aad8e6f81	doc/ide: add node package This will be used to publish the docs in a way that is easy for pybricks-code to use.	2021-01-25 20:50:02 -06:00
David Lechner	e9c2492514	doc/ide: use sphinx.ext.imgmath MathJax uses a CDN to to distribute the package. So in order to use the docs offline, we would have to include our own copy. But it is a bit large (50-ish MB), so it is easier to use sphinx.ext.imgmath instead to generate svg images. The situation might be different with MathJax v3, but that requires Sphinx v4.	2021-01-25 20:48:08 -06:00
David Lechner	9ae1a991f0	doc/api/signaltypes: use ^{\circ} instead of ° in :math: This works for both sphinx.ext.mathjax and sphinx.ext.imgmath.	2021-01-25 20:36:22 -06:00
David Lechner	232f507954	doc/api/signaltypes: fix degree symbol overlapping The degree symbol was a bit too close to the letters.	2021-01-25 20:24:46 -06:00
David Lechner	afba297c41	doc/ide: hide the "view source" link Since these are meant to be offline docs and use a smaller screen area we can omit this to keep things cleaner.	2021-01-25 20:24:46 -06:00
David Lechner	6b5932b8b8	doc/ide: hide prev/next buttons In the IDE this is more of a reference and less of a book so going to the next page doesn't make as much sense.	2021-01-25 20:24:42 -06:00
David Lechner	424de0adde	doc: open external links in a new window This adds a hack to open external links in a new window. Requires Sphinx v1.8.	2021-01-24 20:23:44 -06:00
David Lechner	44f6bd8258	doc: override external link style on figure target This works around https://github.com/readthedocs/sphinx_rtd_theme/pull/494#issuecomment-354063112	2021-01-24 19:58:46 -06:00
David Lechner	7bc2728da3	doc/ide: hide footers This information is duplicated in the IDE about dialog so we don't need it in the docs.	2021-01-24 17:05:51 -06:00