Merge pull request #87 from numtide/initial_docs

Added initial document files

Author: zimbatm

.github/workflows/gh-pages.yml

@@ -0,0 +1,44 @@
+name: Deploy docs
+
+on:
+    push:
+        branches:
+            - main
+        tags:
+            - "v*"
+
+    # Allows you to run this workflow manually from the Actions tab
+    workflow_dispatch:
+
+jobs:
+    deploy:
+        runs-on: ubuntu-24.04
+        permissions:
+            contents: write
+        concurrency:
+            group: ${{ github.workflow }}
+        steps:
+            - uses: actions/checkout@v4
+              with:
+                  fetch-depth: 0
+            - uses: cachix/install-nix-action@V27
+              with:
+                  extra_nix_config: |
+                      accept-flake-config = true
+                      experimental-features = nix-command flakes
+            - name: Configure Git user
+              run: |
+                  git config --local user.email "github-actions[bot]@users.noreply.github.com"
+                  git config --local user.name "github-actions[bot]"
+            - name: Deploy main
+              if: ${{ github.ref_name == 'main' }}
+              run: |
+                  nix develop .#docs --command bash -c "mike deploy -p main"
+            - name: Deploy version
+              if: startsWith(github.ref, 'refs/tags/v')
+              run: |
+                  REF_NAME=${{ github.ref_name }}
+                  MAJOR_MINOR=${REF_NAME%.*}
+                  # strip the leading v from the ref_name
+                  # update the latest alias          
+                  nix develop .#docs --command bash -c "mike deploy -p -u ${MAJOR_MINOR} latest"

.gitignore

@@ -0,0 +1 @@
+site/

docs/content/assets/images/logo.png

@@ -0,0 +1,3 @@
+# Contributing
+
+Coming soon!

docs/content/contributing/code.md

@@ -0,0 +1,14 @@
+# Examples
+
+# TODO
+
+Adding new inputs to the top flake.nix file
+
+# TODO
+
+Building a starter template / boilerplate for future projects
+
+If you tend to use the same toolset...
+
+
+

docs/content/examples/examples.md

@@ -0,0 +1,160 @@
+*[todo: We need to put together a short style guide for consistency, including*
+* Nix (not nix)
+* NixOS (not NixOs etc.) 
+* Should we say "folder" or "directory"? Younger people seem to prefer "folder" ]
+
+# Installing Blueprint
+
+Let's create a small project with Nix, and you'll see how to add Blueprint to your project.
+
+1. Install [Nix](https://nix.dev/install-nix).
+2. Run `mkdir my-project && cd my-project`
+3. Run `nix flake init -t github:numtide/blueprint`.
+
+Note: After you install Nix, you'll need to enable "experimental features." Find out how here.
+
+This will give you a barebone project structure with a single `flake.nix` file and a single `devshell.nix` file. (It also provides a basic .envrc, which [TODO] and a starter .gitignore file. Make sure you're aware of this .gitignore file before you accidentally overwrite it.)
+
+Normally, without Blueprint, you would typically include a devShell section inside your flake.nix file. In that scenario, when you want to start a new project with a similar toolset, you'll likely need to copy over the devShell section of your flake.nix file to the new project's flake.nix file. But by using Blueprint, we've split out the devShell into its own file, allowing you to simply copy the file over.
+
+Here's the starting point of your devShell.nix file:
+
+```nix
+{ pkgs }:
+pkgs.mkShell {
+  # Add build dependencies
+  packages = [ ];
+
+  # Add environment variables
+  env = { };
+
+  # Load custom bash code
+  shellHook = ''
+
+  '';
+}
+```
+
+In a moment we'll look at what you can do with this file. Meanwhile, here's the flake.nix file:
+
+```
+{
+  description = "Simple flake with a devshell";
+
+  # Add all your dependencies here
+  inputs = {
+    nixpkgs.url = "github:NixOS/nixpkgs?ref=nixos-unstable";
+    blueprint.url = "github:numtide/blueprint";
+    blueprint.inputs.nixpkgs.follows = "nixpkgs";
+  };
+
+  # Load the blueprint
+  outputs = inputs: inputs.blueprint { inherit inputs; };
+}
+```
+
+You generally shouldn't have to modify this file (unless you're adding new inputs).
+
+When you run a nix command (such as `nix develop`), this flake.nix file is evaluated and Nix loads the Blueprint into the Nix store and makes it available to your current session. Blueprint in turn allows you to read .nix files from multiple locations within your project, including:
+
+* The devShell.nix file in the root of your project
+* A folder structure
+
+You create the folder structure based on the available list of folders (found here).
+
+# A Sample Environment
+
+Let's set up a development environment that includes:
+
+* Python
+* Python's numpy package
+
+Open up the devshell.nix file in your favorite editor, and update it to look like this:
+
+```nix
+{ pkgs }:
+pkgs.mkShell {
+  # Add build dependencies
+  packages = [
+    pkgs.python3
+    pkgs.python3Packages.numpy
+  ];
+
+  # Add environment variables
+  env = { };
+
+  # Load custom bash code
+  shellHook = ''
+    export PS1="(python numpy) $PS1"
+  '';
+}
+```
+
+Notice we added two packages, Python and the NumPy Python package.
+
+We also added a line inside shellHook. (This line is not required, but it's handy, as it updates the prompt to let you know when you're inside a nix shell.)
+
+Now let's hop into the developer shell by typing:
+
+```bash
+nix develop
+```
+
+After a short moment where Nix downloads the packages, you'll be inside the shell. To verify the packages were installed, type:
+
+```bash
+python
+```
+
+Then, inside python type:
+
+```
+import numpy
+```
+
+You shouldn't see any error.
+
+That's it; go ahead and exit python by typing
+
+```bash
+quit()
+```
+
+When you're ready to exit the development shell, you can simply type:
+
+```bash
+exit
+```
+
+## What did this demonstrate? 
+
+The above demonstrated that the devshell.nix file is now self-contained and can be used without having to add devshell code inside your flake.nix file.
+
+There's much more, however, that you can do.
+
+Check out:
+
+* Examples (including the rest of our Python/NumPy example)
+* Guides
+* Contributing
+
+# (Optional) Configuring direnv
+
+Included in the initial files created by Blueprint is a filed called .envrc. This file contains code to configure direnv, which allows you to enter a devshell simply by switching to the folder containing your project. That means you don't need to type `nix develop` after entering the folder. Then when you move up and out of the folder, you'll automatically exit the environment.
+
+For more information on configuring this feature, check out our guide at [Configuring Direnv](../guides/configuring_direnv.md)
+
+
+## Creating a root folder
+
+
+
+
+
+## Adding a host
+
+TODO
+
+## Adding a package
+
+TODO

docs/content/getting-started/install.md

@@ -0,0 +1,141 @@
+# Configuring Direnv to speed up loading developer environments
+
+Included in the initial files created by Blueprint is a filed called .envrc. This file contains code to configure direnv, which allows you to enter a devshell simply by switching to the folder containing your project. That means you don't need to type `nix develop` after entering the folder. Then when you move up and out of the folder, you'll automatically exit the environment.
+
+## 1. Install direnv. If you're using NixOS:
+
+In the bash shell, type:
+
+```bash
+cd /etc/nixos
+```
+
+Then open the file called `configuration.nix` using sudo in conjunction with your favorite editor. For example, if you're using vim:
+
+```bash
+sudo vi configuration.nix
+```
+
+Locate the line starting with `environment.systemPackages` and add the direnv package, similar to the following:
+
+```bash
+environment.systemPackages = with pkgs; [ vim git direnv ];
+```
+
+(In this example, I already had vim and git installed.)
+
+## 2. Add a shell hook
+
+Now return to your home folder and open .envrc:
+
+```
+cd ~
+vi .bashrc
+```
+
+Add the following line to the end of the file:
+
+```bash
+eval "$(direnv hook bash)"
+```
+
+Save the file and exit. Then either:
+* Log out and log back in or
+* Run the same eval command manually to activate it
+
+Now direnv is running. Switch to a folder containing a Flake/Blueprint project you previously created. For this example we'll use the one we created in the install page, which includes Python and Python's NumPy package.
+
+```bash
+cd python_numpy
+```
+
+Note that the first time you do this, you will encounter an error:
+
+```bashrc
+direnv: error /home/nixos/dev/python_numpy/.envrc is blocked. Run `direnv allow` to approve its content
+```
+
+Go ahead and type:
+
+```bash
+direnv allow
+```
+
+Then direnv will automatically launch the devshell for you. Try it! In this case, because we have Python and NumPy installed, type:
+
+```bash
+python
+```
+
+and a Python shell should open. Then type:
+
+```python
+import numpy
+```
+
+Press Enter and you'll see it loaded without an error. Type
+
+```python
+exit()
+```
+
+## 3. Updating devshell.nix
+
+Direnv will automatically reload and relaunch your developer environemnt quietly behind the scenes if you update your devshell.nix file. Let's try it out. Let's add in the pandas library. 
+
+First, verify that pandas is *not* installed. From within Python, try to import pandas; after the error message, exit out of Python:
+
+```python
+>>> import pandas
+Traceback (most recent call last):
+  File "<stdin>", line 1, in <module>
+ModuleNotFoundError: No module named 'pandas'
+>>>
+>>> exit()
+```
+
+Now open devshell.nix in your favorite editor, and add the pandas package:
+
+```nix
+{ pkgs }:
+pkgs.mkShell {
+  # Add build dependencies
+  packages = [
+    pkgs.python3
+    pkgs.python3Packages.numpy
+    pkgs.python3Packages.pandas
+  ];
+
+  # Add environment variables
+  env = { };
+
+  # Load custom bash code
+  shellHook = ''
+
+  '';
+}
+```
+Save it, and you'll briefly see direnv kick in and display some messages. Now return to Python and you'll see that you now have the Pandas package available.
+
+```python
+>>> import pandas
+>>> 
+>>> exit()
+```
+
+## 4. Exiting the development shell
+
+Finally Now cd up and out of the current folder:
+
+```bash
+cd ...
+```
+
+You'll see the message:
+
+```bash
+direnv: unloading
+```
+
+And now to see that you've left the developer environment, try typing ```python``` again and you should see a ```command not found``` error.
+

docs/content/guides/configuring_direnv.md

@@ -0,0 +1,7 @@
+---
+template: home.html
+search:
+    exclude: true
+---
+
+# Home