This is an automated email from the ASF dual-hosted git repository.
xiaoxiang pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/nuttx.git
The following commit(s) were added to refs/heads/master by this push:
new bd90132cd64 tools/nix: split flake into root and Documentation
bd90132cd64 is described below
commit bd90132cd64a5a3be28496f1278d92e8c44febac
Author: Côme VINCENT <44554692+com...@users.noreply.github.com>
AuthorDate: Mon Aug 11 16:26:46 2025 -0400
tools/nix: split flake into root and Documentation
Root flake now only contains dependencies needed for building the NuttX
firmware. The Documentation flake contains the dependencies needed for
running `make html`.
Updated the documentation accordingly.
Signed-off-by: Côme VINCENT <44554692+com...@users.noreply.github.com>
---
Documentation/flake.lock | 27 +++++++++
Documentation/flake.nix | 77 +++++++++++++++++++++++++
Documentation/guides/nix_flake.rst | 113 +++++++++++++++++++++++++++++--------
flake.lock | 33 ++++++++++-
flake.nix | 18 ++----
5 files changed, 233 insertions(+), 35 deletions(-)
diff --git a/Documentation/flake.lock b/Documentation/flake.lock
new file mode 100644
index 00000000000..7469d879ea0
--- /dev/null
+++ b/Documentation/flake.lock
@@ -0,0 +1,27 @@
+{
+ "nodes": {
+ "nixpkgs": {
+ "locked": {
+ "lastModified": 1754725699,
+ "narHash": "sha256-iAcj9T/Y+3DBy2J0N+yF9XQQQ8IEb5swLFzs23CdP88=",
+ "owner": "NixOS",
+ "repo": "nixpkgs",
+ "rev": "85dbfc7aaf52ecb755f87e577ddbe6dbbdbc1054",
+ "type": "github"
+ },
+ "original": {
+ "owner": "NixOS",
+ "ref": "nixos-unstable",
+ "repo": "nixpkgs",
+ "type": "github"
+ }
+ },
+ "root": {
+ "inputs": {
+ "nixpkgs": "nixpkgs"
+ }
+ }
+ },
+ "root": "root",
+ "version": 7
+}
diff --git a/Documentation/flake.nix b/Documentation/flake.nix
new file mode 100644
index 00000000000..659174d7d01
--- /dev/null
+++ b/Documentation/flake.nix
@@ -0,0 +1,77 @@
+{
+ description = "Sphinx documentation environment with sphinx-tags";
+
+ inputs = {
+ nixpkgs.url = "github:NixOS/nixpkgs/nixos-unstable";
+ };
+
+ outputs =
+ { self, nixpkgs }:
+ let
+ system = "x86_64-linux";
+ pkgs = import nixpkgs { inherit system; };
+
+ python = pkgs.python313;
+
+ sphinx-tags = python.pkgs.buildPythonPackage rec {
+ pname = "sphinx-tags";
+ version = "0.4";
+
+ src = pkgs.fetchPypi {
+ pname = "sphinx_tags";
+ inherit version;
+ sha256 = "MGUhm6z0dWfHBvIjfVZlsi86UWc2e0xFaLzaQ3GlNZ0=";
+ };
+
+ pyproject = true;
+ build-system = [ python.pkgs.flit-core ];
+
+ propagatedBuildInputs = with python.pkgs; [
+ sphinx
+ ];
+
+ doCheck = false;
+ };
+
+ sphinx-collapse = python.pkgs.buildPythonPackage rec {
+ pname = "sphinx_collapse";
+ version = "0.1.3";
+
+ src = pkgs.fetchPypi {
+ inherit version pname;
+ sha256 = "yuFB5vA+zVLtJGowWmnhsNXQXmzfP+gD1A1YOtatiVo=";
+ };
+
+ pyproject = true;
+ build-system = [ python.pkgs.flit-core ];
+
+ propagatedBuildInputs = with python.pkgs; [
+ sphinx
+ ];
+
+ doCheck = false;
+ };
+
+ nuttx-doc-py-env = python.withPackages (
+ ps: with ps; [
+ sphinx
+ sphinx_rtd_theme
+ myst-parser
+ sphinx-tabs
+ sphinx-autobuild
+ sphinx-copybutton
+ sphinx-togglebutton
+ pytz
+ importlib-metadata
+ sphinx-design
+ sphinx-tags
+ sphinx-collapse
+ ]
+ );
+ in
+ {
+ devShells.${system}.default = pkgs.mkShell {
+ buildInputs = [ nuttx-doc-py-env ];
+ };
+ };
+}
diff --git a/Documentation/guides/nix_flake.rst
b/Documentation/guides/nix_flake.rst
index a6dc7de21ae..3fb8a63e5c4 100644
--- a/Documentation/guides/nix_flake.rst
+++ b/Documentation/guides/nix_flake.rst
@@ -2,18 +2,23 @@
Nix Flake for Reproducible Development
======================================
-This guide explains how to use the Nix flake to set up a reproducible
development environment for NuttX. The Nix flake ensures that all required
build tools and dependencies are consistently available, simplifying onboarding
and reducing "works on my machine" issues.
+This guide explains how to use the Nix flake to set up a reproducible
+development environment for NuttX. The Nix flake ensures that all required
+build tools and dependencies are consistently available, simplifying
+onboarding and reducing "works on my machine" issues.
Prerequisites
-------------
-* `Nix <https://nixos.org/download/>`_ installed on your system.
-* Nix flakes enabled (add ``experimental-features = nix-command flakes`` to
your ``nix.conf``).
+* `Nix <https://nixos.org/download/>`_ installed on your system.
+* Nix flakes enabled (add ``experimental-features = nix-command flakes``
+ to your ``nix.conf``).
Setting up the Development Environment
--------------------------------------
-To enter the NuttX development shell, navigate to the root of the NuttX
directory and run:
+To enter the **NuttX build** development shell, navigate to the root of
+the NuttX directory and run:
.. code-block:: bash
@@ -21,29 +26,77 @@ To enter the NuttX development shell, navigate to the root
of the NuttX director
This command will:
-* Download and set up all necessary build tools and dependencies, including:
- * CMake, Ninja, GNU Make
- * Clang tools
- * ARM toolchain (gcc-arm-embedded)
- * Automake, Bison, Flex, Genromfs, Gettext, Gperf
- * Kconfig-frontends, libelf, expat, gmp, isl, libmpc, mpfr, ncurses, zlib
- * Python with kconfiglib
-* Set the ``CMAKE_EXPORT_COMPILE_COMMANDS`` environment variable to ``ON``.
-* Display a welcome message.
+* Download and set up all necessary build tools and dependencies, including:
+
+ * CMake, Ninja, GNU Make
+ * Clang tools
+ * ARM toolchain (gcc-arm-embedded)
+ * Automake, Bison, Flex, Genromfs, Gettext, Gperf
+ * Kconfig-frontends, libelf, expat, gmp, isl, libmpc, mpfr, ncurses, zlib
+ * Python with kconfiglib
+
+* Set the ``CMAKE_EXPORT_COMPILE_COMMANDS`` environment variable to ``ON``.
+* Display a welcome message.
Once inside the development shell, you can proceed with building NuttX as
usual.
+Setting up the Documentation Environment
+-----------------------------------------
+
+The flake also provides a **documentation** development shell that includes
+Sphinx and all required extensions for building the NuttX documentation.
+
+To enter the documentation shell, run:
+
+.. code-block:: bash
+
+ nix develop .#docs
+
+This command will:
+
+* Provide Python 3.13 with Sphinx and extensions, including:
+
+ * sphinx-rtd-theme
+ * myst-parser
+ * sphinx-tabs
+ * sphinx-autobuild
+ * sphinx-copybutton
+ * sphinx-togglebutton
+ * sphinx-design
+ * sphinx-tags
+ * sphinx-collapse
+ * pytz, importlib-metadata
+
+* Allow you to build and preview the documentation without installing
+ anything globally.
+
+Example usage:
+
+.. code-block:: bash
+
+ # Build HTML docs
+ make html
+
+See the :doc:`/contributing/documentation` guide for more details.
+
Benefits
--------
-* **Reproducibility:** Ensures a consistent build environment across all
developers and machines.
-* **Simplified Onboarding:** New contributors can quickly set up their
development environment with a single command.
-* **Dependency Management:** All dependencies are managed by Nix, avoiding
conflicts with system-wide packages.
+* **Reproducibility:** Ensures a consistent build environment across all
+ developers and machines.
+* **Simplified Onboarding:** New contributors can quickly set up their
+ development environment with a single command.
+* **Dependency Management:** All dependencies are managed by Nix, avoiding
+ conflicts with system-wide packages.
+* **Separate Environments:** Keep firmware build tools and documentation
+ tools isolated, or combine them if needed.
Contents of the Nix Flake
-------------------------
-The `flake.nix` file defines a `devShell` that includes the following build
inputs:
+The `flake.nix` file defines two `devShells`:
+
+* ``devShells.default`` - NuttX build environment:
.. code-block:: nix
@@ -76,13 +129,29 @@ The `flake.nix` file defines a `devShell` that includes
the following build inpu
pkgs.python313Packages.kconfiglib
];
-The `shellHook` sets up the `CMAKE_EXPORT_COMPILE_COMMANDS` and provides a
welcome message:
-
-.. code-block:: nix
-
shellHook = ''
export CMAKE_EXPORT_COMPILE_COMMANDS=ON
echo "Welcome to NuttX devShell"
'';
-This setup ensures that the development environment is fully configured for
NuttX development.
+* ``devShells.docs`` - Documentation environment (from
`Documentation/flake.nix`):
+
+.. code-block:: nix
+
+ python.withPackages (ps: with ps; [
+ sphinx
+ sphinx_rtd_theme
+ myst-parser
+ sphinx-tabs
+ sphinx-autobuild
+ sphinx-copybutton
+ sphinx-togglebutton
+ sphinx-design
+ sphinx-tags
+ sphinx-collapse
+ pytz
+ importlib-metadata
+ ]);
+
+This setup ensures that both firmware development and documentation building
+are fully reproducible and isolated.
diff --git a/flake.lock b/flake.lock
index 80a25ac1f41..26ab4e5ba8a 100644
--- a/flake.lock
+++ b/flake.lock
@@ -1,5 +1,19 @@
{
"nodes": {
+ "documentation": {
+ "inputs": {
+ "nixpkgs": "nixpkgs"
+ },
+ "locked": {
+ "path": "./Documentation",
+ "type": "path"
+ },
+ "original": {
+ "path": "./Documentation",
+ "type": "path"
+ },
+ "parent": []
+ },
"flake-utils": {
"inputs": {
"systems": "systems"
@@ -19,6 +33,22 @@
}
},
"nixpkgs": {
+ "locked": {
+ "lastModified": 1754725699,
+ "narHash": "sha256-iAcj9T/Y+3DBy2J0N+yF9XQQQ8IEb5swLFzs23CdP88=",
+ "owner": "NixOS",
+ "repo": "nixpkgs",
+ "rev": "85dbfc7aaf52ecb755f87e577ddbe6dbbdbc1054",
+ "type": "github"
+ },
+ "original": {
+ "owner": "NixOS",
+ "ref": "nixos-unstable",
+ "repo": "nixpkgs",
+ "type": "github"
+ }
+ },
+ "nixpkgs_2": {
"locked": {
"lastModified": 1753250450,
"narHash": "sha256-i+CQV2rPmP8wHxj0aq4siYyohHwVlsh40kV89f3nw1s=",
@@ -36,8 +66,9 @@
},
"root": {
"inputs": {
+ "documentation": "documentation",
"flake-utils": "flake-utils",
- "nixpkgs": "nixpkgs"
+ "nixpkgs": "nixpkgs_2"
}
},
"systems": {
diff --git a/flake.nix b/flake.nix
index 91ab4197846..8dd08be4778 100644
--- a/flake.nix
+++ b/flake.nix
@@ -4,6 +4,7 @@
inputs = {
nixpkgs.url = "github:NixOS/nixpkgs/nixos-unstable";
flake-utils.url = "github:numtide/flake-utils";
+ documentation.url = "path:./Documentation";
};
outputs =
@@ -11,6 +12,7 @@
self,
nixpkgs,
flake-utils,
+ documentation,
...
}:
flake-utils.lib.eachDefaultSystem (
@@ -19,6 +21,7 @@
pkgs = import nixpkgs { inherit system; };
in
{
+ # Default devShell
devShells.default = pkgs.mkShell {
buildInputs = [
# Build tools
@@ -47,24 +50,15 @@
pkgs.ncurses.dev
pkgs.zlib
pkgs.python313Packages.kconfiglib
-
- # NuttX Documentation
- pkgs.sphinx
- pkgs.python313Packages.sphinx_rtd_theme
- pkgs.python313Packages.myst-parser
- pkgs.python313Packages.sphinx-tabs
- pkgs.python313Packages.sphinx-autobuild
- pkgs.python313Packages.sphinx-copybutton
- pkgs.python313Packages.sphinx-togglebutton
- pkgs.python313Packages.pytz
- pkgs.python313Packages.importlib-metadata
- pkgs.python313Packages.sphinx-design
];
shellHook = ''
export CMAKE_EXPORT_COMPILE_COMMANDS=ON
echo "Welcome to NuttX devShell"
'';
};
+
+ # Documentation devShell
+ devShells.docs = documentation.devShells.${system}.default;
}
);
}
