implement the vision

Co-authored-by: Valentin Gagarin <valentin.gagarin@tweag.io>
NixOS · Oct 16, 2023 · 98c296d · 98c296d
1 parent 1dddf60
commit 98c296d
Show file tree

Hide file tree

Showing 35 changed files with 90 additions and 199 deletions.
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -3,7 +3,6 @@
 nix.dev is a community effort to collect, create, and maintain world-class learning resources for Nix.
 
 It is supposed to fit between first impressions on the [Nix web site](https://nixos.org) and the reference manuals for [Nix][nix manual] ([source][nix manual src]), [Nixpkgs][nixpkgs manual] ([source][nixpkgs manual src]), and [NixOS][nixos manual] ([source][nixos manual src]).
-See the [vision](#vision) and [textual outline](#outline) for an idea of a desired end state.
 
 [nix manual]: https://nixos.org/manual/nix
 [nix manual src]: https://github.com/NixOS/nix/tree/master/doc/manual

diff --git a/_redirects b/_redirects
@@ -14,3 +14,22 @@
 /tutorials/integration-testing-using-virtual-machines /tutorials/nixos/integration-testing-using-virtual-machines 301
 /contributing/writing-style /contributing/style-guide 301
 /tutorials/nixos/build-and-deploy/* /tutorials/nixos/:splat 301
+/recipes/faq /concepts/faq 301
+/tutorials/install-nix /install-nix 301
+/reference/pinning-nixpkgs recipes/pinning-nixpkgs 301
+/tutorials/learning-journey/sharing-dependencies /recipes/sharing-dependencies 301
+/tutorials/first-steps/towards-reproducibility-pinning-nixpkgs /recipes/towards-reproducibility-pinning-nixpkgs 301
+/tutorials/nixos/building-and-running-docker-images /tutorials/building-testing-and-deploying-software/building-and-running-docker-images
+/tutorials/nixos/continuous-integration-github-actions /tutorials/building-testing-and-deploying-software/continuous-integration-github-actions 301
+/tutorials/cross-compilation /tutorials/building-testing-and-deploying-software/cross-compilation
+/tutorials/nixos/deploying-nixos-using-terraform /tutorials/building-testing-and-deploying-software/deploying-nixos-using-terraform 301
+/tutorials/nixos/integration-testing-using-virtual-machines /tutorials/building-testing-and-deploying-software/integration-testing-using-virtual-machines 301
+/tutorials/nixos/building-bootable-iso-image /tutorials/declarative-user-environments-and-system-configurations/building-bootable-iso-image 301
+/tutorials/nixos/installing-nixos-on-a-raspberry-pi /tutorials/declarative-user-environments-and-system-configurations/installing-nixos-on-a-raspberry-pi 301
+/tutorials/nixos/nixos-configuration-on-vm /tutorials/declarative-user-environments-and-system-configurations/nixos-configuration-on-vm 301
+/tutorials/first-steps/nix-language /tutorials/nix-language 301
+/tutorials/first-steps/ad-hoc-shell-environments /tutorials/temporary-environments/ad-hoc-shell-environments 301
+/tutorials/first-steps/declarative-and-reproducible-developer-environments /tutorials/temporary-environments/declarative-and-reproducible-developer-environments 301
+/tutorials/first-steps/reproducible-scripts /tutorials/temporary-environments/reproducible-scripts 301
+/tutorials/learning-journey/shell-dot-nix /tutorials/temporary-environments/shell-dot-nix 301
+/tutorials/learning-journey/packaging-existing-software /tutorials/using-customising-and-creating-packages/packaging-existing-software 301
diff --git a/source/recipes/faq.md → source/concepts/faq.md b/source/recipes/faq.md → source/concepts/faq.md
diff --git a/source/index.md b/source/index.md
@@ -47,7 +47,7 @@ Explanations of history and ideas in the Nix ecosystem
 :::
 ::::
 
-If you're new to the Nix ecosystem, begin your journey with {ref}`First Steps <first-steps>`!
+If you're new to the Nix ecosystem, begin your journey with our tutorial series!
 
 ## What can you do with Nix?
 
@@ -77,6 +77,7 @@ The following illustrate of what can be achieved with the Nix ecosystem:
 ```{toctree}
 :hidden:
 
+install-nix.md
 tutorials/index.md
 recipes/index.md
 reference/index.md

diff --git a/source/tutorials/install-nix.md → source/install-nix.md b/source/tutorials/install-nix.md → source/install-nix.md
diff --git a/source/recipes/index.md b/source/recipes/index.md
@@ -8,5 +8,7 @@ These sections contains guides to getting things done.
 :maxdepth: 2
 
 *
-../templates/*
+Combining multiple Nixpkgs releases <https://github.com/nixos/nix.dev/issues>
+Sharing dependencies between `default.nix` and `shell.nix` <https://github.com/nixos/nix.dev/issues>
+Troubleshooting <https://github.com/nixos/nix.dev/issues>
 ```
diff --git a/source/reference/pinning-nixpkgs.md → source/recipes/pinning-nixpkgs.md b/source/reference/pinning-nixpkgs.md → source/recipes/pinning-nixpkgs.md
diff --git a/.../learning-journey/sharing-dependencies.md → source/recipes/sharing-dependencies.md b/.../learning-journey/sharing-dependencies.md → source/recipes/sharing-dependencies.md
diff --git a/...owards-reproducibility-pinning-nixpkgs.md → ...owards-reproducibility-pinning-nixpkgs.md b/...owards-reproducibility-pinning-nixpkgs.md → ...owards-reproducibility-pinning-nixpkgs.md
diff --git a/source/reference/index.md b/source/reference/index.md
@@ -10,7 +10,7 @@ These sections contains collections of detailed technical descriptions.
 Nix Reference Manual <https://nixos.org/manual/nix/stable/>
 Nixpkgs Manual <https://nixos.org/manual/nixpkgs/stable/>
 NixOS Manual <https://nixos.org/manual/nixos/stable/>
-pinning-nixpkgs.md
-glossary.md
+Recommended support tools <https://github.com/nix-community/awesome-nix>
 ../recommended-reading.md
+glossary.md
 ```
diff --git a/source/templates/index.md b/source/templates/index.md
diff --git a/...xos/building-and-running-docker-images.md → ...are/building-and-running-docker-images.md b/...xos/building-and-running-docker-images.md → ...are/building-and-running-docker-images.md
diff --git a/.../continuous-integration-github-actions.md → .../continuous-integration-github-actions.md b/.../continuous-integration-github-actions.md → .../continuous-integration-github-actions.md
diff --git a/source/tutorials/cross-compilation.md → ...d-deploying-software/cross-compilation.md b/source/tutorials/cross-compilation.md → ...d-deploying-software/cross-compilation.md
diff --git a/.../nixos/deploying-nixos-using-terraform.md → ...ftware/deploying-nixos-using-terraform.md b/.../nixos/deploying-nixos-using-terraform.md → ...ftware/deploying-nixos-using-terraform.md
diff --git a/source/tutorials/building-testing-and-deploying-software/index.md b/source/tutorials/building-testing-and-deploying-software/index.md
@@ -0,0 +1,17 @@
+(building-testing-and-deploying-software)=
+# Building, testing, and deploying software
+
+```{toctree}
+:glob:
+:maxdepth: 2
+
+Setting up a Binary Cache <https://github.com/NixOS/nix.dev/issues>
+Setting up Distributed Builds <https://github.com/NixOS/nix.dev/issues>
+cross-compilation.md
+continuous-integration-github-actions.md
+Building and running NixOS containers <https://github.com/nixos/nix.dev/issues>
+building-and-running-docker-images.md
+Building and running virtual machines in NixOS <https://github.com/nixos/nix.dev/issues>
+integration-testing-using-virtual-machines.md
+deploying-nixos-using-terraform.md
+```
diff --git a/...gration-testing-using-virtual-machines.md → ...gration-testing-using-virtual-machines.md b/...gration-testing-using-virtual-machines.md → ...gration-testing-using-virtual-machines.md
diff --git a/...ials/nixos/building-bootable-iso-image.md → ...igurations/building-bootable-iso-image.md b/...ials/nixos/building-bootable-iso-image.md → ...igurations/building-bootable-iso-image.md
diff --git a/source/tutorials/declarative-user-environments-and-system-configurations/index.md b/source/tutorials/declarative-user-environments-and-system-configurations/index.md
@@ -0,0 +1,17 @@
+(declarative-user-environments-and-system-configurations)=
+# Declarative user environments and system configurations
+
+```{toctree}
+:glob:
+:maxdepth: 2
+
+Declarative user environments with Home Manager <https://github.com/nixos/nix.dev/issues>
+Dependency Management with Niv <https://github.com/nixos/nix.dev/issues>
+Editor configuration with Home Manager <https://github.com/nixos/nix.dev/issues>
+nixos-configuration-on-vm.md
+Installing NixOS <https://github.com/nixos/nix.dev/issues>
+installing-nixos-on-a-raspberry-pi.md
+Using NixOS Modules <https://github.com/nixos/nix.dev/issues>
+building-bootable-iso-image.md
+Custom NixOS modules <https://github.com/NixOS/nix.dev/issues/337>
+```
diff --git a/...xos/installing-nixos-on-a-raspberry-pi.md → ...ons/installing-nixos-on-a-raspberry-pi.md b/...xos/installing-nixos-on-a-raspberry-pi.md → ...ons/installing-nixos-on-a-raspberry-pi.md
diff --git a/...orials/nixos/nixos-configuration-on-vm.md → ...nfigurations/nixos-configuration-on-vm.md b/...orials/nixos/nixos-configuration-on-vm.md → ...nfigurations/nixos-configuration-on-vm.md
diff --git a/source/tutorials/first-steps/dev-environment.md b/source/tutorials/first-steps/dev-environment.md
diff --git a/source/tutorials/first-steps/index.md b/source/tutorials/first-steps/index.md
diff --git a/source/tutorials/index.md b/source/tutorials/index.md
@@ -7,9 +7,11 @@ These sections contains series of lessons to get started.
 :glob:
 :maxdepth: 2
 
-install-nix.md
-first-steps/index.md
-learning-journey/index.md
-nixos/index.md
-cross-compilation.md
+temporary-environments/index.md
+nix-language.md
+using-customising-and-creating-packages/index.md
+declarative-user-environments-and-system-configurations/index.md
+building-testing-and-deploying-software/index.md
+Debugging Builds <https://github.com/nixos/nix.dev/issues>
+Debugging Expressions <https://github.com/nixos/nix.dev/issues>
 ```
diff --git a/source/tutorials/learning-journey/index.md b/source/tutorials/learning-journey/index.md
diff --git a/source/tutorials/learning-journey/template.md b/source/tutorials/learning-journey/template.md
diff --git a/source/tutorials/first-steps/nix-language.md → source/tutorials/nix-language.md b/source/tutorials/first-steps/nix-language.md → source/tutorials/nix-language.md
diff --git a/source/tutorials/nixos/index.md b/source/tutorials/nixos/index.md
diff --git a/.../first-steps/ad-hoc-shell-environments.md → ...environments/ad-hoc-shell-environments.md b/.../first-steps/ad-hoc-shell-environments.md → ...environments/ad-hoc-shell-environments.md
diff --git a/...nd-reproducible-developer-environments.md → ...nd-reproducible-developer-environments.md b/...nd-reproducible-developer-environments.md → ...nd-reproducible-developer-environments.md
diff --git a/source/tutorials/temporary-environments/index.md b/source/tutorials/temporary-environments/index.md
@@ -0,0 +1,12 @@
+(temporary-environments)=
+# Temporary Environments
+
+```{toctree}
+:glob:
+:maxdepth: 2
+
+ad-hoc-shell-environments.md
+reproducible-scripts.md
+declarative-and-reproducible-developer-environments.md
+shell-dot-nix.md
+```
diff --git a/...rials/first-steps/reproducible-scripts.md → ...rary-environments/reproducible-scripts.md b/...rials/first-steps/reproducible-scripts.md → ...rary-environments/reproducible-scripts.md
diff --git a/...torials/learning-journey/shell-dot-nix.md → ...s/temporary-environments/shell-dot-nix.md b/...torials/learning-journey/shell-dot-nix.md → ...s/temporary-environments/shell-dot-nix.md
diff --git a/source/tutorials/using-customising-and-creating-packages/index.md b/source/tutorials/using-customising-and-creating-packages/index.md
@@ -0,0 +1,11 @@
+(using-customising-and-creating-packages)=
+# Using, customising, and creating packages
+
+```{toctree}
+:glob:
+:maxdepth: 2
+
+Customising Packages with Overrides <https://github.com/NixOS/nix.dev/issues/678>
+packaging-existing-software.md
+Nixpkgs Overlays <https://github.com/NixOS/nix.dev/issues/116>
+```
diff --git a/...ng-journey/packaging-existing-software.md → ...g-packages/packaging-existing-software.md b/...ng-journey/packaging-existing-software.md → ...g-packages/packaging-existing-software.md