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-09-13 01:56:55 +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
408 changed files with 2516 additions and 6567 deletions
@@ -31,8 +31,8 @@ jobs:
        node-version: '14.x'
        registry-url: 'https://registry.npmjs.org'
    - run: yarn build
-      working-directory: doc/main
+      working-directory: doc/ide
    - run: yarn publish
-      working-directory: doc/main
+      working-directory: doc/ide
      env:
        NODE_AUTH_TOKEN: ${{ secrets.NODE_AUTH_TOKEN }}
@@ -1,7 +1,7 @@
 # This workflow will install Python dependencies, run tests and lint with a variety of Python versions
 # For more information see: https://help.github.com/actions/language-and-framework-guides/using-python-with-github-actions

-name: Build Python package and docs
+name: Python package

 on: [ push, pull_request ]

@@ -40,4 +40,4 @@ jobs:
        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 TAG=ide
+      run: poetry run make -C doc html SOURCEDIR=ide
@@ -1,22 +0,0 @@
-name: Release to PyPI
-
-on:
-  release:
-    types: [published]
-
-jobs:
-  build_and_publish:
-    runs-on: ubuntu-20.04
-    steps:
-    - uses: actions/checkout@v2
-    - uses: actions/setup-python@v2
-      with:
-        python-version: 3.8
-    - uses: abatilo/actions-poetry@v2.0.0
-      with:
-        poetry-version: 1.1.6
-    - run: poetry install
-    - run: poetry build
-    - run: poetry publish
-      env:
-        POETRY_PYPI_TOKEN_PYPI: ${{ secrets.PYPI_TOKEN }}
@@ -1,22 +0,0 @@
-# .readthedocs.yaml
-# Read the Docs configuration file
-# See https://docs.readthedocs.io/en/stable/config-file/v2.html for details
-#
-# Settings in the readthedocs online dashboard will be ignored.
-
-# Required
-version: 2
-
-# Build documentation in the doc/main directory with Sphinx
-sphinx:
-   configuration: doc/main/conf.py
-
-# Build your docs in additional formats such as PDF
-formats:
-   - pdf
-
-# Set the version of Python and requirements required to build the docs
-python:
-   version: 3.8
-   install:
-   - requirements: rtd-requirements.txt
@@ -6,7 +6,7 @@
    "python.linting.enabled": true,
    "python.languageServer": "Pylance",
    "files.associations": {"*.inc": "restructuredtext"},
-    "restructuredtext.confPath": "${workspaceFolder}/doc/main",
+    "restructuredtext.confPath": "${workspaceFolder}/doc/api",
    "spellright.language": [
        "en_US"
    ],
@@ -1,79 +0,0 @@
-# Changelog
-
-<!-- refer to https://keepachangelog.com/en/1.0.0/ for guidance -->
-
-## 3.1.0rc1 - 2021-11-19
-
-### Added
- Added `ColorLightMatrix` class.
- Added `LWP3Device` class.
-
-**NOTE: version number after this point were from JavaScript package and do
-not correspond to Pybricks firmware version numbers.**
-
-## 1.6.0 - 2021-08-30
-
-### Added
- MicroPython module documentation.
- Examples for hub system functions including stop button and shutdown.
-
-### Changed
- Build IDE docs as main docs with minor changes, instead of a completely
-  separate build.
- Moved motor control documentation to the motor page.
-
-## 1.5.0 - 2021-07-01
-
-### Added
- Documentation for Powered Up Remote Control.
-
-## 1.4.0 - 2021-06-23
-
-### Added
- Enabled beta content that was hidden for the 3.0 release.
- Added notice about using the latest beta version.
-
-## 1.3.3 - 2021-05-21
-
-### Changed
- Match example snippet styling to IDE.
- Add more examples.
-
-## 1.3.2 - 2021-04-26
-
-## Changed
- Theme style fixes.
- Example code fixes
- Match doc version to firmware version.
-
-## 1.3.1 - 2021-04-12
-
-### Changed
- Upgrade sphinx and rtd-theme to fix style issues.
-
-## 1.3.0 - 2021-04-12
-
-### Removed
- Removed features which not be in the official 3.0 release. These features
-  are still in beta. They'll come back in future releases once tested.
-
-## 1.2.0 - 2021-04-09
-
-### Changed
- Moved installation guide to external site.
-
-## 1.1.1 - 2021-02-14
-
-### Added
- Added installation guide.
- Various documentation fixes.
-
-## 1.1.0 - 2021-01-28
-
-### Added
- Scrollbar styling.
-
-## 1.0.0 - 2021-01-25
-
-### Added
- Sphinx build output.
@@ -20,23 +20,20 @@ will actually be implemented.

 - Commit messages have a one-line subject, a blank line and a multiline body:

-        prefix: Subject of the change.
+        prefix: subject

        body...

- Use a prefix to categorize the change:
-  - Use the import path as the prefix whenever possible. Examples:
-     - pybricks.tools: Add StopWatch class.
-     - pybricks.tools: Reorganize RST files.
-     - pybricks.tools.StopWatch: Fix return type.
-     - pybricks.tools.wait: Add example of waiting.
-     - pybricks.pupdevices: Fix all sensor class ports.
-     - umath.sin: Fix spelling of Hypotenuse.
-  - If an import path makes no sense, just use the file path without extensions:
-     - .vscode/settings: Fix file associations.
- The subject briefly describes _what_ was changed. Use a short full sentence as in the examples above.
+- Use a prefix to categorize the change. Usually this is the path the the file
+  being changed. 
+  - If it is a documentation change, it can be shortened to `doc/<file>` (omit
+    `api` from the path).
+  - If it is an API change (in the `pybricks` folder), write `api/<file>` 
+    instead of `pybricks/<file>`.
+- The subject briefly describes _what_ was changed, e.g. `fix typo`.
 - The body describes _why_ the change was made, e.g. `The word "sensor" was
  spelled incorrectly`.
+- See the [commit history][commits] for more examples.

 [commits]: https://github.com/pybricks/pybricks-api/commits/master

@@ -62,24 +59,15 @@ Build docs:

    # Linux
    poetry run make -C doc html
-    xdg-open doc/main/build/html/index.html
+    xdg-open doc/api/build/html/index.html

    # macOS
    poetry run make -C doc html
-    open doc/main/build/html/index.html
+    open doc/api/build/html/index.html

    # Windows (PowerShell)
    poetry run doc\make.bat html
-    Invoke-Item doc\main\build\html\index.html
-
-Building IDE docs variant:
-
-    # Linux/macOS
-    poetry run make -C doc html TAG=ide
-
-    # Windows (PowerShell)
-    $env:TAG="ide"
-    poetry run doc\make.bat html
+    Invoke-Item doc\api\build\html\index.html

 Linting:

@@ -5,13 +5,12 @@
 SPHINXOPTS    = -W
 SPHINXBUILD   = sphinx-build
 SPHINXPROJ    = Pybricks
-SOURCEDIR     = main
+SOURCEDIR     = api
 BUILDDIR      = "$(SOURCEDIR)"/build
-TAG           = main

 # Put it first so that "make" without argument is like "make help".
 help:
-	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) -t $(TAG) $(O)
+	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)

 .PHONY: help Makefile

@@ -22,4 +21,4 @@ diagrams:
 # Catch-all target: route all unknown targets to Sphinx using the new
 # "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
 %: Makefile
-	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) -t $(TAG) $(O)
+	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
@@ -0,0 +1,22 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+#
+# Pybricks documentation build configuration file
+#
+import os
+
+# General information about the project.
+project = 'pybricks'
+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.'
+
+html_favicon = '../common/images/favicon.ico'
+html_logo = '../common/images/pybricks-logo-rtd.png'
+latex_logo = '../common/images/pybricks-logo-large.png'
+
+exec(open(os.path.abspath("../common/conf.py")).read())
--- a/Show More
+++ b/Show More
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