Merge pull request #1 from modelblocks-org/remove-clio

Update documentation to modelblocks

Author: irm-codebase

.github/ISSUE_TEMPLATE/bug_report.md

@@ -0,0 +1,27 @@
+---
+name: Bug report
+about: For general problems with the documentation
+title: ''
+labels: bug
+assignees: ''
+
+---
+
+**Describe the bug**
+A clear and concise description of what the issue is.
+
+**To Reproduce**
+Steps to reproduce the issue:
+1. Go to '...'
+2. Click on '....'
+3. Scroll down to '....'
+4. See error
+
+**Expected behavior**
+A clear and concise description of what you expected to happen.
+
+**Screenshots**
+If applicable, add screenshots to help explain your problem.
+
+**Additional context**
+Add any other context about the problem here.

.github/ISSUE_TEMPLATE/config.yml

@@ -0,0 +1,5 @@
+blank_issues_enabled: false
+contact_links:
+  - name: General information
+    url: https://www.modelblocks.org/
+    about: Please reach out through our website for general questions.

.github/ISSUE_TEMPLATE/guideline-suggestion.md

@@ -0,0 +1,20 @@
+---
+name: Guideline suggestion
+about: Suggest an idea to make modelblocks better!
+title: ''
+labels: enhancement
+assignees: ''
+
+---
+
+**Is this suggestion related to a problem? Please describe.**
+A clear and concise description of what the problem is. Ex. I'm always frustrated when [...]
+
+**Describe the solution you'd like**
+A clear and concise description of what you want to happen.
+
+**Describe alternatives you've considered**
+A clear and concise description of any alternative solutions or features you've considered.
+
+**Additional context**
+Add any other context or screenshots about the feature request here.

.github/workflows/pr-ci.yml

@@ -0,0 +1,19 @@
+name: CI
+
+on:
+  pull_request:
+    branches: [ main ]
+
+jobs:
+  build:
+    name: Build
+    runs-on: ${{ matrix.os }}
+    strategy:
+      matrix:
+        os: [ubuntu-latest]
+    steps:
+      - uses: actions/checkout@v4
+      - name: setup-pixi
+        uses: prefix-dev/setup-pixi@v0.9.4
+      - name: Run tests
+        run: pixi run test

.gitignore

@@ -14,7 +14,6 @@ build/
 dist/
 wheels/
 *.egg-info
-src/clio_tools/_version.py
 
 # Virtual environments
 .venv

CITATION.cff

@@ -3,7 +3,7 @@
 # https://citation-file-format.github.io/
 cff-version: 1.2.0
 message: Please cite this project using the metadata from this file.
-title: "modelblocks - Re-usable building blocks for energy system models"
+title: "modelblocks - Reusable building blocks for energy system models"
 repository: https://github.com/modelblocks-org/docs
 license: Apache 2.0
 version: 0.0.1

README.md

@@ -1,15 +1,23 @@
-# A framework for modular and easy to understand energy modelling tools
+# Modelblocks documentation
 
-`clio` aims to be a collection modularisation guidelines and tools that help energy modellers produce high-quality research that is repeatable, understanable and easy to use.
+`modelblocks` aims to be a collection modular tools and modularisation guidelines that help energy modellers produce high-quality research that is repeatable, understanable, and easy to use.
 
-Please read all about it in our [documentation](https://clio.readthedocs.io/en/stable/)!
+Please read all about it in our [documentation](https://modelblocks.readthedocs.io/en/stable/)!
 
-## `clio` development
+## `modelblocks` documentation development
 
-Install [`pixi`](https://pixi.sh/latest/) and run:
+We rely on [`pixi`](https://pixi.sh/latest/) for development and maintenance.
+To install, simply run the following:
 
 ```bash
-git clone git@github.com:calliope-project/clio.git
-cd clio
-pixi install --all  # Installs both default and developer dependencies
+git clone git@github.com:modelblocks-org/docs.git
+cd docs
+pixi install --all
 ```
+
+## Helper commands
+
+- `pixi run build-docs`: build a local version of the documentation
+- `pixi run serve-docs`: render the documentation on your browser
+- `pixi run style`: run CI linting, refractoring and spellchecking
+- `pixi run test`: quick local test of the documentation

docs/Background/our_framework.md

@@ -42,29 +42,31 @@ These are topic-specific data-generating [`snakemake`](https://snakemake.github.
     Below is an example of how a data module can be accessed by another workflow.
 
     ```python
-    # Include local module configuration.
-    configfile: "config/modules/foobar.yaml"
+    # Load the module configuration
+    with open(workflow.source_path("config/geoboundaries.yaml"), "r") as file:
+        config_geoboundaries = yaml.safe_load(file.read())
 
-    module foobar:
+    module geoboundaries:
         # Request a specific module version.
         snakefile:
             github(
-                "calliope-project/foobar",
+                "modelblocks-org/module_geo_boundaries",
                 path="workflow/Snakefile",
-                tag="v1.0.0"
+                tag="v0.1.9"
             )
-        # Module configuration has its own key to ensure isolation.
-        config: config["foobar"]
-        # A prefix is added to isolate module input/output files.
-        prefix: "results/module_foobar"
+        # Specify the module configuration.
+        config: config_geoboundaries
+        # Pathvars let you tune input/output file location.
+        pathvars:
+            shapes="results/module_geoboundaries/shapes.parquet"
 
     # Rewrite rule names to avoid naming conflicts
-    use rule * from foobar as module_foobar_*
+    use rule * from geoboundaries as module_geoboundaries_*
     ```
 
 ??? note "Template"
 
-    All data modules should follow [our standardised template](https://github.com/calliope-project/data-module-template).
+    All data modules should follow [our standardised template](https://github.com/modelblocks-org/data-module-template).
     This template provides a baseline for developers to ensure the following.
 
     - Version-specific access via version tags.
@@ -81,9 +83,9 @@ These are study-specific workflows that combine the outputs of all other types o
     Since they tend to be study-specific, they will rarely (if ever) be accessed by other tools or components.
     It is perfectly possible to ensure that a model builder can be accessed modularly, but this is not required.
 
-## The `clio_tools` integration utilities
+## The `clio_tools` integration utility
 
-To save time and enable component developers to check against the latest `clio` standards, we provide the `clio_tools` library.
+To save time and enable component developers to check against the latest `modelblocks` standards, we provide the `clio_tools` library.
 This is a set of useful utility functions, geared towards ensuring smooth interfacing.
 
-For more information, check [`clio_tools`](https://github.com/modelblocks-org/clio-tools)
+For more information, check [`clio_tools`](https://github.com/modelblocks-org/clio-tools).

docs/Developer_guidelines/getting_started.md

@@ -13,10 +13,10 @@ If you don't, we recommend following `mamba`'s [installation advice](https://git
     mamba install -c conda-forge copier
     ```
 
-2. Call the `copier` template of the type of component you wish to make. Currently, we only support [data modules](https://github.com/calliope-project/data-module-template).
+2. Call the `copier` template of the type of component you wish to make. Currently, we only support [data modules](https://github.com/modelblocks-org/data-module-template).
 
     ```shell
-    copier copy 'https://github.com/calliope-project/data-module-template'
+    copier copy 'https://github.com/modelblocks-org/data-module-template'
     ```
 
 3. You'll be prompted with some questions. After answering them, `copier` will auto-generate the module for you.

docs/Developer_guidelines/requirements.md

@@ -4,7 +4,7 @@
 
 We enforce the following requirements in all projects.
 
-1. **Open-source code**: projects must use either MIT or Apache 2.0, which are both [OSI approved](https://opensource.org/licenses) open-source licenses, and they must be openly available in platforms such as GitHub.
+1. **Open-source code**: projects must use either Apache 2.0 or MIT open-source licenses, which are [OSI approved](https://opensource.org/licenses), and they must be openly available in platforms such as GitHub.
 2. **Open data**: data produced by projects (dataset tools and data modules in particular) should use a [CC-BY-4.0 license](https://creativecommons.org/licenses/by/4.0/) whenever possible.
 3. **Versioning**: projects must be version controlled with official releases, which can be used to specify the version of the project used in a study and/or dataset, and an accompanying CHANGELOG. Project developers are free to choose their preferred approach (e.g., [SemVer](https://semver.org/) or [CalVer](https://calver.org/)).
 4. **Testing**: projects must employ some type of testing to ensure quality and long-term stability. The approach will vary depending on the type of project:
@@ -46,7 +46,7 @@ The following is a list of general advice on how to format files to help tools i
 
         ???+ example "Example of a tidy table"
 
-            | year          | country_id       | shape_id         | demand       |
+            | year          | country_id       | shape_id         | demand_mwh   |
             |---------------|------------------|------------------|--------------|
             | 2020          | ITA              | North            | 4500         |
             | 2020          | ITA              | East             | 4800         |
@@ -68,20 +68,13 @@ The following is a list of general advice on how to format files to help tools i
                 "shape_id": "no_unit",
                 "demand": "mwh"
                 }
-            dataframe.attrs["source"] = "github.com/calliope-project/clio"
+            dataframe.attrs["source"] = "github.com/modelblocks-org/docs"
             dataframe.attrs["license"] = "CC-BY-4.0"
             dataframe.to_parquet('my_data.parquet')
             ```
 
 3. **Raster data**: we prefer to use GeoTIFF (.tiff) files.
 4. **Polygon data**: we prefer [GeoParquet](https://geoparquet.org/) (.parquet) files.
-
-    ??? example "Example shapefiles in our standard format"
-
-        You can find some simple examples of our standard data format in the `clio/resources/shapes` folder.
-
-        --8<-- "resources/shapes/README.md:docs"
-
 5. **Gridded data**: we prefer to use [netCDF](https://www.unidata.ucar.edu/software/netcdf/) (.nc) files.
 
 ## Metadata conventions
@@ -95,7 +88,7 @@ The following is a list of general advice on how to format files to help tools i
 
     ???+ example "Example of tabular subnational data"
 
-        | country_id       | shape_id         | shape_spec       | demand       |
+        | country_id       | shape_id         | shape_spec       | demand_mwh   |
         |------------------|------------------|------------------|--------------|
         | DEU              | DE13             | NUTS2024         | 4500         |
         | DEU              | DE14             | NUTS2024         | 4800         |