Add raidex tutorial

doc/pages/packaging.md

@@ -0,0 +1,58 @@
+# Packaging
+
+Packaging your components allows others to easily use them.
+RAIMAD packages are just Python packages,
+so if you already know how to make Python packages,
+you have a good headstart.
+If you don't,
+I'll do my best to explain.
+
+## Choosing a name for your package
+
+You should choose a short and informative name for your package.
+In addition to the
+[PEP8 requirement](https://peps.python.org/pep-0008/#package-and-module-names)
+of using only lowercase letters,
+we also require all RAIMAD packages to start with `rai_`
+in order to make it clear that the package contains RAIMAD components.
+
+## Set up your package
+
+You can use
+[`rai_smiley`](https://github.com/tifuun/rai_smiley)
+as an example of how to set up a package.
+If you've never made a Python package before,
+you can read through the README file,
+which hopefully explains everything.
+
+## Add to RAIDEX
+
+[RAIDEX](https://tifuun.github.io/raidex/)
+is RAIMAD's package index.
+It allows users to easily discover existing components.
+It is highly encouraged to add your package to RAIDEX.
+
+### Add RAIDEX metadata
+
+> [ WORKINPROGRESS ]
+>
+> I'm still writing this section.
+
+Once you've added the relevant metadata,
+read the README on
+[RAIDEX's gitub](https://github.com/tifuun/raidex)
+for setting up RAIDEX locally.
+This will allow you to see how your components will look like
+on the publc RAIDEX instance,
+and help you catch any errors.
+
+Once you're satisfied with how you package looks in RAIDEX,
+you can contact the [RAIDEX maintainer](people.md) to publish it.
+
+> [ INFO ]
+>
+> Are you a TIFUUN collaborator?
+> If so, you can add your package to RAIDEX directly,
+> without going through the RAIDEX mainteiner.
+> [Learn how](raidex-tifuun-public.md)
+

doc/pages/people.md

@@ -0,0 +1,9 @@
+# Contact
+
+RAIMAD is part of the
+[TIFUUN project](https://cordis.europa.eu/project/id/101043486).
+If you're not a TIFUUN collaborator
+but would like to get involved with RAIMAD,
+you can contact maybetree48 *at* proton *dot* me
+for any questions or requests.
+

doc/pages/raidex-tifuun-private.md

@@ -0,0 +1,89 @@
+# Adding your (private) package to RAIDEX
+
+> [ INFO ]
+>
+> This page is for TIFUUN collaborators.
+> If you're an external user who wants to
+> add your package to RAIDEX,
+> you should contact the [RAIDEX maintainer](people.md) instead.
+
+> [ INFO ]
+>
+> For this guide we assume that your code is hosted on a
+> private github repo,
+> so that only people of your choosing can view your
+> source code.
+> Do you have a public github repo? Then go to the guide for
+> [public packages](raidex-tifuun-public.md)
+
+
+So, you've
+[set up your package](packaging.md)
+and want to add it to RAIDEX.
+Good!
+
+## Add deploy key
+
+If you package is hosted on a private github repo,
+you need to grant RAIDEX access to that repo.
+This can be done through so-called "deploy keys".
+
+1. Navigate to the "settings" tab in the top bar of your repo page
+1. Navigate to "deploy keys" under "security" in the sidebar
+1. Click "add deploy key"
+1. Add the RAIDEX public key
+
+The RAIDEX public key is as follows:
+
+```
+ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIEd6Zx1h9EnoLZDJDSiU78kMbzMxCRZwOoBiHdIndHjs
+```
+
+## Add your package to the requirements file
+
+Next, clone the
+[RAIDEX repository](https://github.com/tifuun/raidex).
+Then, open the file `deploy/raidex-packages.txt`
+and add a line for your package
+in the following format format:
+
+```
+git+ssh://[email protected]/<user-or-org>/<repository-name>.git
+```
+
+So, for example, if the HTTP url to your package is
+<https://github.com/tifuun/rai_smiley>,
+then you would add
+`git+ssh://[email protected]/tifuun/rai_smiley.git`
+
+Once you are done, commit your changes and push.
+
+> [ DANGER ]
+> Since you have write access to the RAIDEX repository,
+> it is easy for you to exfiltrate the RAIDEX private key,
+> which you can use to read other people's private repositories.
+>
+> We trust that you do not do this.
+>
+> We also trust that you follow good cybersecurity practices
+> and keep your github account safe.
+
+## Debugging your package deployment
+
+Once you've pushed your changes to raidex,
+a runner should pick up the updated workflow file
+and rebuild raidex.
+You can check on how it is going in the
+"Actions" tab of the raidex repository on github.
+If something goes wrong, you can also read the error log there.
+
+> [ INFO ]
+>
+> If your commit results in a failed build,
+> do not panic.
+> The last good version of raidex will still be available
+> to everyone else.
+> Read the error message,
+> fix it,
+> and push again.
+

doc/pages/raidex-tifuun-public.md

@@ -0,0 +1,96 @@
+# Adding your (public) package to RAIDEX
+
+> [ INFO ]
+>
+> This page is for TIFUUN collaborators.
+> If you're an external user who wants to
+> add your package to RAIDEX,
+> you should contact the [RAIDEX maintainer](people.md) instead.
+
+> [ INFO ]
+>
+> For this guide we assume that your code is hosted on a
+> public github repo, so that your code is available for the world
+> to read.
+> Do you have a private github repo? Then go to the guide for
+> [private packages](raidex-tifuun-private.md)
+
+So, you've
+[set up your package](packaging.md)
+and want to add it to RAIDEX.
+Good!
+
+## Add your package to the requirements file
+
+Clone the
+[RAIDEX repository](https://github.com/tifuun/raidex).
+Then, open the file `deploy/raidex-packages.txt`
+and add a line for your package
+in the following format format:
+
+```
+git+https://github.com/<user-or-org>/<repo-name>.git
+```
+
+So, for example, if the HTTP url to your package is
+<https://github.com/tifuun/rai_smiley>,
+then you would add
+`git+https://github.com/tifuun/rai-smiley.git`
+
+Once you are done, commit your changes and push.
+
+> [ DANGER ]
+>
+> Since you have write access to the RAIDEX repository,
+> it is easy for you to exfiltrate the RAIDEX private key,
+> which you can use to read other people's private repositories.
+>
+> We trust that you do not do this.
+>
+> We also trust that you follow good cybersecurity practices
+> and keep your github account safe.
+
+## Debugging your package deployment
+<!-- TODO this section is copy-pasted.
+We need snippets!! -->
+
+Once you've pushed your changes to raidex,
+a runner should pick up the updated workflow file
+and rebuild raidex.
+You can check on how it is going in the
+"Actions" tab of the raidex repository on github.
+If something goes wrong, you can also read the error log there.
+
+> [ INFO ]
+>
+> If your commit results in a failed build,
+> do not panic.
+> The last good version of raidex will still be available
+> to everyone else.
+> Read the error message,
+> fix it,
+> and push again.
+
+## Optional: publish to PyPI
+
+If you want to make it easier for others to install
+your package,
+you should publish it to PyPI.
+[Python's official documentation](https://packaging.python.org/en/latest/tutorials/packaging-projects/)
+goes in-depth on how to do this.
+But generally,
+it boils down to the following steps:
+
+1. Create a PyPI account
+1. Create an API token for your account
+1. Install [twine](https://pypi.org/project/twine/)
+1. Inside of your package:
+    1. `python -m build`
+    1. `python -m twine upload dist/rai_yourpackage-x.x.x*`
+1. Verify that it worked: `pip install rai_yourpackage`
+
+Once you have your package on pypi,
+you can replace your line in the
+`raidex-packages.txt` file
+with the name of your package.
+

doc/pages/tutorial.md

@@ -11,4 +11,6 @@ or jump to any part of the tutorial using the table of contents below.
 1. [Builtin components](builtin-compos.md)
 1. [Coordinates and Transformations](coords-transforms.md)
 1. [Layers](layers.md)
+1. [Packaging](packaging.md)
+
 

doc/scss/root.scss

@@ -273,7 +273,15 @@ blockquote {
 	//border-left: 5px solid black;
 	//padding-left: 15px;
 	//border-radius: 10px 10px 10px 10px;
+	margin: 0px;
 	flex-grow: 1;
+	display: flex;
+	flex-direction: column;
+	gap: 10px;
+
+	& p {
+		margin: 0px;
+	}
 }
 
 

pyproject.toml

@@ -4,10 +4,8 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "raidoc"
-version = "1.0.4.0"
-description = """\
-Documentation for RAIMAD
-"""
+version = "1.0.4.1"
+description = "Documentation for RAIMAD"
 authors = [
 	{name = "maybetree", email = "[email protected]"}
 	]