diff --git a/doc/pages/github-pages.md b/doc/pages/github-pages.md deleted file mode 100644 index 9778c03..0000000 --- a/doc/pages/github-pages.md +++ /dev/null @@ -1,91 +0,0 @@ -# Github Pages - -> [INFO] -> This page is about maintaining RAIDOC. -> It is intended to be useful to anyone who may take over the -> project after me in the future. - -> [DANGER] -> This page contains elevated quantities of sodium - -RAIDOC is hosted with github pages. -Github pages is a service for hosting static HTML sites. -RAIDOC is compiled to HTML and deployed to pages -using a thing called "github actions". -Actions is basically a hook that runs code whenever something -gets committed to `main` branch. -The actions configurations is inside of `.github/workflows/deploy.md`. - -Where does the code run? -Inside of a "runner". -Github provides their own runners, -but I went with self-hosted. -For now, -the runner for RAIDOC -is emprisoned inside of a docker container on my laptop. -The dockerfile is as follows: - -```Dockerfile -#FROM alpine:latest -#FROM ghcr.io/void-linux/void-glibc-busybox:46f5dc6 -FROM ghcr.io/void-linux/void-glibc-full:46f5dc6 -# glibc is needed for the runner -# gnu tar as opposed to busybox tar is needed for upload artifact action!?! - -ARG GH_TOKEN -RUN test "$GH_TOKEN" || { echo "need github token"; exit 1; } - -WORKDIR actions-runner - -RUN \ - `# apk update `&& \ - `#apk add` \ - `# curl` \ - `# perl-utils` `# for shasum` \ - `# bash` \ - `# dotnet6-sdk` `# screw you microsoft!! ` && \ - xbps-install -Syu \ - curl \ - bash \ - perl `# for shasum`\ - shadow `# for useradd and groupadd` \ - icu icu-libs `# for github runner` \ - `# the rest are for raidoc` \ - graphviz \ - python3 - -RUN \ - curl -o microsoft-sucks.tar.gz -L 'https://download.visualstudio.microsoft.com/download/pr/886b4a4c-30af-454b-8bec-81c72b7b4e1f/d1a0c8de9abb36d8535363ede4a15de6/dotnet-sdk-3.0.100-linux-x64.tar.gz' && \ - mkdir /microsoft-sucks && \ - tar xzf microsoft-sucks.tar.gz -C /microsoft-sucks - -RUN \ - curl -o actions-runner-linux-x64-2.316.1.tar.gz -L https://github.com/actions/runner/releases/download/v2.316.1/actions-runner-linux-x64-2.316.1.tar.gz && \ - echo "d62de2400eeeacd195db91e2ff011bfb646cd5d85545e81d8f78c436183e09a8 actions-runner-linux-x64-2.316.1.tar.gz" | shasum -a 256 -c && \ - tar xzf ./actions-runner-linux-x64-2.316.1.tar.gz - -RUN \ - `#addgroup -S runner` && \ - `#adduser -S runner -G runner` && \ - groupadd runner && \ - useradd runner -g runner && \ - chown -R runner:runner . - -USER runner -ENV DOTNET_ROOT=/microsoft-sucks - -RUN \ - ./config.sh \ - --url https://github.com/maybeetree/raidoc \ - --token "$GH_TOKEN" \ - --agent "orth-docker-void" - -ENTRYPOINT ["./run.sh"] -``` - -If it is not obvious from the dockerfile, -I am upset with github somehow needing full glibc, gnu coreutils, -and dotnet to make a program whose only purpose is to download code, -run it, and upload artifacts. -This wouldn't've been an issue with gitlab. - diff --git a/doc/pages/packaging.md b/doc/pages/packaging.md new file mode 100644 index 0000000..1a8ab2e --- /dev/null +++ b/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) + diff --git a/doc/pages/people.md b/doc/pages/people.md new file mode 100644 index 0000000..13e1184 --- /dev/null +++ b/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. + diff --git a/doc/pages/raidex-tifuun-private.md b/doc/pages/raidex-tifuun-private.md new file mode 100644 index 0000000..9dc8e01 --- /dev/null +++ b/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://git@github.com//.git +``` + +So, for example, if the HTTP url to your package is +, +then you would add +`git+ssh://git@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 + +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. + diff --git a/doc/pages/raidex-tifuun-public.md b/doc/pages/raidex-tifuun-public.md new file mode 100644 index 0000000..86b5d82 --- /dev/null +++ b/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//.git +``` + +So, for example, if the HTTP url to your package is +, +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 + + +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. + diff --git a/doc/pages/tutorial.md b/doc/pages/tutorial.md index d75b6c1..ac9c175 100644 --- a/doc/pages/tutorial.md +++ b/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) + diff --git a/doc/scss/root.scss b/doc/scss/root.scss index 7912883..ab9171a 100644 --- a/doc/scss/root.scss +++ b/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; + } } diff --git a/pyproject.toml b/pyproject.toml index 7a62da0..3ab2563 100644 --- a/pyproject.toml +++ b/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 = "maybetree48@proton.me"} ] diff --git a/src/raidoc/raimark_ext.py b/src/raidoc/raimark_ext.py index 0c9c593..0c3afb9 100644 --- a/src/raidoc/raimark_ext.py +++ b/src/raidoc/raimark_ext.py @@ -62,6 +62,22 @@ def render_quote(self, element): '', )) + def render_paragraph(self, element): + + # TODO fix this monstrosity + # this was added to prevent empty paragraph + # when you do a callout label, + # then line skip with a single `>` + # then the callout body + + if not element.children: + return '' + if not element.children[0].children: + return '' + if not element.children[0].children[0]: + return '' + return super().render_paragraph(element) + class EmphasisMixin(object):