@pybricks/ide-docs v1.3.3

This is not officially supported yet, so drop from release docs.

.github/workflows/build.yml

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

.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,84 +0,0 @@
-# Changelog
-
-<!-- refer to https://keepachangelog.com/en/1.0.0/ for guidance -->
-
-## Unreleased
-
-### Fixed
-- Fixed link to Color Light Matrix 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())