@pybricks/ide-docs v1.3.1

This is mainly to pull in the requirement of docutils < 0.17 from
sphinx-rtd-theme. Just bumping to latest sphinx doc while we are at it.

Issue: https://github.com/pybricks/pybricks-api/issues/55

.github/workflows/publish-ide-docs.yml

@@ -31,8 +31,8 @@ jobs:
         node-version: '14.x'
         registry-url: 'https://registry.npmjs.org'
     - run: yarn build
-      working-directory: npm/ide-docs
+      working-directory: doc/ide
     - run: yarn publish
-      working-directory: npm/ide-docs
+      working-directory: doc/ide
       env:
         NODE_AUTH_TOKEN: ${{ secrets.NODE_AUTH_TOKEN }}

.github/workflows/pythonpackage.yml

@@ -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

.github/workflows/release-to-pypi.yml

@@ -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 }}

.readthedocs.yaml

@@ -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

.vscode/settings.json

@@ -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"
     ],

CHANGELOG.md

@@ -1,93 +0,0 @@
-# Changelog
-
-<!-- refer to https://keepachangelog.com/en/1.0.0/ for guidance -->
-
-## 3.1.0 - 2021-12-16
-
-### Added
-- Added maximum voltage setter for `DCMotor` and `Motor`.
-- Documented `DriveBase.curve()` method.
-
-### Changed
-- Removed `duty` setting from `Control.limits` method.
-- Removed `integral_range` setting from `Control.pid` method.
-
-### Fixed
-- Fixed link to Color Light Matrix page.
-- Fixed link to Inventor Hub page.
-
-## 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.

CONTRIBUTING.md

@@ -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:
 

doc/Makefile

@@ -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)

doc/api/conf.py

@@ -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())

doc/api/diagram_source/pupmotors.ldr

@@ -0,0 +1,13 @@
+0 Name: pupmotors.ldr
+0 Author: Pybricks {laurens@pybricks.com}
+0 !LICENSE MIT
+0 ROTATION CENTER 0 0 0 1 "Custom" 
+0 ROTATION CONFIG 0 0
+1 15 430 -96 190 0 0 1 1 0 0 0 1 0 54675c01.dat
+1 15 430 -96 400 0 0 1 1 0 0 0 1 0 54675c01.dat
+1 322 430 -72 30 0 0 1 1 0 0 0 1 0 54696c01.dat
+1 71 430 -72 -180 0 0 1 1 0 0 0 1 0 54696c01.dat
+1 71 190 -144 -180 1 0 0 0 1 0 0 0 1 22169c01.dat
+1 71 -20 -216 -140 1 0 0 0 1 0 0 0 1 22172c01.dat
+1 15 120 -320 160 1 0 0 0 1 0 0 0 1 26913c01.dat
+0

doc/api/diagram_source/pupmotors.svg

@@ -11,8 +11,8 @@
    xmlns:sodipodi="http://sodipodi.sourceforge.net/DTD/sodipodi-0.dtd"
    xmlns:inkscape="http://www.inkscape.org/namespaces/inkscape"
    width="2000"
-   height="1126"
-   viewBox="0 0 529.16666 297.92083"
+   height="1118"
+   viewBox="0 0 529.16666 295.80416"
    version="1.1"
    id="svg8"
    inkscape:version="0.92.3 (2405546, 2018-03-11)"
@@ -58,8 +58,8 @@
      inkscape:pageopacity="0.0"
      inkscape:pageshadow="2"
      inkscape:zoom="0.35"
-     inkscape:cx="930.75599"
-     inkscape:cy="703.45816"
+     inkscape:cx="619.19211"
+     inkscape:cy="823.24691"
      inkscape:document-units="mm"
      inkscape:current-layer="layer1"
      showgrid="false"
@@ -87,18 +87,18 @@
      inkscape:label="Layer 1"
      inkscape:groupmode="layer"
      id="layer1"
-     transform="translate(0,0.92084997)">
+     transform="translate(0,-1.1958167)">
     <image
        sodipodi:absref="pupmotors.png"
        xlink:href="pupmotors.png"
-       y="-0.92085403"
-       x="0"
-       id="image876"
+       width="529.16669"
+       height="295.80417"
        preserveAspectRatio="none"
-       height="297.92084"
-       width="529.16669" />
+       id="image853"
+       x="-2.220446e-16"
+       y="1.1958181" />
     <g
-       transform="matrix(1.9732825,0,0,1.9732825,94.897251,-184.86922)"
+       transform="matrix(1.9732825,0,0,1.9732825,82.068314,-182.19652)"
        id="g2717">
       <g
          transform="matrix(1,-0.27773651,0,1,59.387949,102.27922)"
@@ -123,7 +123,7 @@
     </g>
     <g
        id="g2727"
-       transform="matrix(1.7059944,0,0,1.7059944,-93.696445,-190.67567)">
+       transform="matrix(1.7059944,0,0,1.7059944,-18.326438,-250.00951)">
       <g
          style="fill:#2980b9;fill-opacity:1;stroke:#fffbfb;stroke-width:0.13229167;stroke-miterlimit:4;stroke-dasharray:none;stroke-opacity:1"
          id="g2721"
@@ -147,7 +147,7 @@
          sodipodi:nodetypes="ccccsc" />
     </g>
     <g
-       transform="matrix(1.7059944,0,0,1.7059944,105.45138,-208.37975)"
+       transform="matrix(1.7059944,0,0,1.7059944,40.772154,-187.53273)"
        id="g2747">
       <g
          transform="matrix(1,-0.27773651,0,1,61.231459,102.02783)"
@@ -173,7 +173,7 @@
     </g>
     <g
        id="g2757"
-       transform="matrix(1.9732825,0,0,1.9732825,-99.624267,-179.081)">
+       transform="matrix(1.9732825,0,0,1.9732825,-63.81015,-178.54646)">
       <g
          style="fill:#2980b9;fill-opacity:1;stroke:#fffbfb;stroke-width:0.13229167;stroke-miterlimit:4;stroke-dasharray:none;stroke-opacity:1"
          id="g2751"
@@ -196,7 +196,7 @@
          style="fill:#2980b9;fill-opacity:1;stroke:none;stroke-width:0.26458332px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1" />
     </g>
     <g
-       transform="matrix(1.9732825,0,0,1.9732825,-253.27985,-174.39985)"
+       transform="matrix(1.9732825,0,0,1.9732825,-192.3424,-182.95247)"
        id="g2767">
       <g
          transform="matrix(1,-0.27773651,0,1,59.387949,102.27922)"
@@ -221,7 +221,7 @@
     </g>
     <g
        id="g874"
-       transform="matrix(1.9732825,0,0,1.9732825,-208.72093,-333.33743)">
+       transform="matrix(1.9732825,0,0,1.9732825,-208.72093,-323.71573)">
       <g
          style="fill:#2980b9;fill-opacity:1;stroke:#fffbfb;stroke-width:0.13229167;stroke-miterlimit:4;stroke-dasharray:none;stroke-opacity:1"
          id="g868"
@@ -244,7 +244,7 @@
          style="fill:#2980b9;fill-opacity:1;stroke:none;stroke-width:0.26458332px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1" />
     </g>
     <g
-       transform="matrix(1.9732825,0,0,1.9732825,-103.63433,-335.34319)"
+       transform="matrix(1.9732825,0,0,1.9732825,-134.6376,-374.36454)"
        id="g884">
       <g
          transform="matrix(1,-0.27773651,0,1,59.387949,102.27922)"
@@ -275,29 +275,5 @@
        rx="1.295833"
        ry="1.1623898"
        transform="matrix(0.89702138,0.44198716,0,1,0,0)" />
-    <g
-       id="g899"
-       transform="matrix(1.9732825,0,0,1.9732825,15.03334,-338.81769)">
-      <g
-         style="fill:#2980b9;fill-opacity:1;stroke:#fffbfb;stroke-width:0.13229167;stroke-miterlimit:4;stroke-dasharray:none;stroke-opacity:1"
-         id="g893"
-         transform="matrix(1,-0.27773651,0,1,59.387949,102.27922)">
-        <path
-           id="path891"
-           style="fill:#2980b9;fill-opacity:1;fill-rule:evenodd;stroke:#fffbfb;stroke-width:0.13229167;stroke-linejoin:round;stroke-miterlimit:4;stroke-dasharray:none;stroke-opacity:1"
-           d="m 107.60315,149.3339 -4.4195,12.01847 -4.419489,-12.01847 c 2.609269,1.92005 6.179199,1.90899 8.838989,0 z"
-           inkscape:connector-curvature="0" />
-      </g>
-      <path
-         inkscape:connector-curvature="0"
-         id="path895"
-         d="m 148.90956,215.29575 c -8.02867,2.89572 -14.60635,11.81219 -14.60635,19.93021 l 1.74541,-0.62952 c 0,-7.05178 5.7198,-14.86961 12.86094,-17.44522 7.14113,-2.57561 12.86094,1.11628 12.86094,8.16806 l 1.74541,-0.62952 c 0,-8.11802 -6.57768,-12.28973 -14.60635,-9.39401 z"
-         style="color:#000000;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;font-size:medium;line-height:normal;font-family:sans-serif;font-variant-ligatures:normal;font-variant-position:normal;font-variant-caps:normal;font-variant-numeric:normal;font-variant-alternates:normal;font-feature-settings:normal;text-indent:0;text-align:start;text-decoration:none;text-decoration-line:none;text-decoration-style:solid;text-decoration-color:#000000;letter-spacing:normal;word-spacing:normal;text-transform:none;writing-mode:lr-tb;direction:ltr;text-orientation:mixed;dominant-baseline:auto;baseline-shift:baseline;text-anchor:start;white-space:normal;shape-padding:0;clip-rule:nonzero;display:inline;overflow:visible;visibility:visible;opacity:1;isolation:auto;mix-blend-mode:normal;color-interpolation:sRGB;color-interpolation-filters:linearRGB;solid-color:#000000;solid-opacity:1;vector-effect:none;fill:#2980b9;fill-opacity:1;fill-rule:nonzero;stroke:#ffffff;stroke-width:0.1;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:none;stroke-dashoffset:0;stroke-opacity:1;color-rendering:auto;image-rendering:auto;shape-rendering:auto;text-rendering:auto;enable-background:accumulate" />
-      <path
-         inkscape:connector-curvature="0"
-         id="path897"
-         d="m 161.70224,224.65346 1.85836,-0.53454 0.43431,0.40926 -0.98973,1.42822 c 0,0 -2.13398,-0.30486 -2.13398,-0.32574 0,-0.0209 0.83104,-0.9772 0.83104,-0.9772 z"
-         style="fill:#2980b9;fill-opacity:1;stroke:none;stroke-width:0.26458332px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1" />
-    </g>
   </g>
 </svg>

doc/api/diagram_source/pupsensors.ldr

@@ -1,8 +1,7 @@
-0 Name: pupsensors.ldr
+0 Name: pupmotors
 0 Author: Pybricks {laurens@pybricks.com}
 0 !LICENSE MIT
 0 !LDCAD GROUP_DEF [topLevel=true] [LID=0] [GID=9FDP9pj0O55] [name=Group 1] [center=0 0 0]
-1 15 190 -290 750 -1 0 0 0 -1 0 0 0 1 47592c01.dat
 1 15 600 -280 180 1 0 0 0 1 0 0 0 1 37316.dat
 1 15 60 -272 160 -1 0 0 0 -1 0 0 0 1 37312c01.dat
 1 15 -400 -280 240 -1 0 0 0 -1 0 0 0 1 37308c01.dat