Merge pull request #404 from ReactiveBayes/move-examples

Move examples out of the repository

.JuliaFormatter.toml

@@ -24,4 +24,4 @@ align_matrix = false
 join_lines_based_on_source = false
 separate_kwargs_with_semicolon = false
 surround_whereop_typeparameters = true
-ignore = [ "docs", "examples" ]
+ignore = [ "docs" ]

.github/workflows/CI.yml

@@ -35,7 +35,7 @@ jobs:
           # paper.md
           path: paper/paper.pdf
   test:
-    name: Julia ${{ matrix.version }} - ${{ matrix.os }} - ${{ matrix.arch }} - ${{ github.event_name }}
+    name: Tests ${{ matrix.version }} - ${{ matrix.os }} - ${{ matrix.arch }} - ${{ github.event_name }}
     runs-on: ${{ matrix.os }}
     continue-on-error: ${{ contains(matrix.version, 'nightly') }}
     strategy:
@@ -66,44 +66,41 @@ jobs:
         with:
           name: test-output
           path: test/_output
-  examples:
+  test-examples:
     name: Examples
     runs-on: ubuntu-latest
-    permissions:
-      contents: write
     steps:
-      - uses: actions/checkout@v4
+      - name: Checkout RxInfer
+        uses: actions/checkout@v4
+        with:
+          path: RxInfer.jl
+      - name: Checkout Examples
+        uses: actions/checkout@v4
+        with:
+          repository: ReactiveBayes/RxInferExamples.jl
+          path: RxInferExamples.jl
       - uses: julia-actions/setup-julia@v2
-      - uses: julia-actions/cache@v1
-      - uses: julia-actions/julia-buildpkg@v1
-      - uses: actions/cache@v3
-        id: examples
         with:
-          path: |
-            docs/src/examples
-            docs/src/assets/examples
-          key: ${{ github.sha }}
-      - run: make examples
+          version: '1.11'
+      - uses: julia-actions/cache@v1
+      - name: Build and test examples
+        run: |
+          julia -e 'using Pkg; Pkg.add("Weave"); Pkg.develop(path="RxInfer.jl"); Pkg.precompile()'
+          cd RxInferExamples.jl
+          make examples-dev RXINFER=../RxInfer.jl
   docs:
     name: Documentation
     runs-on: ubuntu-latest
     needs: 
       - test
-      - examples
+      - test-examples
     permissions:
       contents: write
     steps:
       - uses: actions/checkout@v2
       - uses: julia-actions/setup-julia@v2
         with:
           version: '1.10' # 1.11 is not supported by Cairo/GraphViz
-      - uses: actions/cache@v3
-        id: examples
-        with:
-          path: |
-            docs/src/examples
-            docs/src/assets/examples
-          key: ${{ github.sha }}
       - uses: julia-actions/cache@v1
       - uses: julia-actions/julia-buildpkg@v1
       - run: make docs

.gitignore

@@ -5,13 +5,6 @@ docs/Manifest.toml
 
 scripts/Manifest.toml
 
-examples/.ipynb_checkpoints
-examples/*incomplete.ipynb
-examples/*.jl
-examples/*WIP*
-examples/*gif
-!examples/.meta.jl
-
 _output
 test/_output
 
@@ -29,8 +22,6 @@ Coverage.ipynb
 
 **/.DS_Store
 
-examples/*Compiled
-
 **/Manifest.toml
 **/LocalPreferences.toml
 !benchmarks/Manifest.toml

Makefile

@@ -11,16 +11,12 @@ else
     PATH_SEP = /
 endif
 
-# Includes `examples/Manifest.toml`
-EXAMPLES_MANIFEST_FILE = examples$(PATH_SEP)Manifest.toml 
-# Includes `examples/Manifest.toml`, `docs/src/examples`, `docs/src/assets/examples`
-EXAMPLES_FILES = $(EXAMPLES_MANIFEST_FILE) docs$(PATH_SEP)src$(PATH_SEP)examples docs$(PATH_SEP)src$(PATH_SEP)assets$(PATH_SEP)examples
 # Includes `docs/build`
 DOCS_BUILD_FILES = docs$(PATH_SEP)build
 # Includes `_output`, `test/_output`
 TEST_OUTPUT_FILES = _output test$(PATH_SEP)_output
 # Includes all the above
-ALL_TMP_FILES = $(EXAMPLES_FILES) $(DOCS_BUILD_FILES) $(TEST_OUTPUT_FILES)
+ALL_TMP_FILES = $(DOCS_BUILD_FILES) $(TEST_OUTPUT_FILES)
 
 .PHONY: lint format
 
@@ -33,36 +29,12 @@ lint: scripts_init ## Code formating check
 format: scripts_init ## Code formating run
 	julia --startup-file=no --project=scripts/ scripts/format.jl --overwrite
 
-.PHONY: examples
-
-examples_init:
-	$(RM) $(EXAMPLES_MANIFEST_FILE)
-	julia --startup-file=no --project=examples/ -e 'using Pkg; Pkg.develop(PackageSpec(path=pwd())); Pkg.instantiate(); Pkg.build(); Pkg.precompile();'
-
-dev_examples_init:
-	$(RM) $(EXAMPLES_MANIFEST_FILE)
-	julia --startup-file=no --project=examples -e 'using Pkg; Pkg.rm([ "RxInfer", "BayesBase", "ExponentialFamily", "ReactiveMP", "GraphPPL", "Rocket" ])'
-	julia --startup-file=no --project=examples -e 'using Pkg; Pkg.develop(PackageSpec(path=joinpath(Pkg.devdir(), "BayesBase.jl")));'
-	julia --startup-file=no --project=examples -e 'using Pkg; Pkg.develop(PackageSpec(path=joinpath(Pkg.devdir(), "ExponentialFamily.jl")));'
-	julia --startup-file=no --project=examples -e 'using Pkg; Pkg.develop(PackageSpec(path=joinpath(Pkg.devdir(), "ReactiveMP.jl")));'
-	julia --startup-file=no --project=examples -e 'using Pkg; Pkg.develop(PackageSpec(path=joinpath(Pkg.devdir(), "GraphPPL.jl")));'
-	julia --startup-file=no --project=examples -e 'using Pkg; Pkg.develop(PackageSpec(path=joinpath(Pkg.devdir(), "Rocket.jl")));' 
-	julia --startup-file=no --project=examples/ -e 'using Pkg; Pkg.develop(PackageSpec(path=pwd())); Pkg.instantiate(); Pkg.precompile();'
-
-examples: scripts_init examples_init ## Precompile examples and put them in the `docs/src/examples` folder (use specific="<pattern>" to compile a specific example)
-	julia --startup-file=no --project=scripts/ scripts/examples.jl $(specific)
-
-devexamples: scripts_init dev_examples_init ## Same as `make examples` but uses `dev-ed` versions of core packages
-	julia --startup-file=no --project=scripts/ scripts/examples.jl $(specific)
-
 .PHONY: docs
 
 doc_init:
-	$(RM) $(EXAMPLES_MANIFEST_FILE)
 	julia --project=docs -e 'using Pkg; Pkg.develop(PackageSpec(path=pwd())); Pkg.instantiate(); Pkg.precompile();'
 
 dev_doc_init:
-	$(RM) $(EXAMPLES_MANIFEST_FILE)
 	julia --startup-file=no --project=docs -e 'using Pkg; Pkg.rm([ "RxInfer", "BayesBase", "ExponentialFamily", "ReactiveMP", "GraphPPL", "Rocket" ])'
 	julia --startup-file=no --project=docs -e 'using Pkg; Pkg.develop(PackageSpec(path=joinpath(Pkg.devdir(), "BayesBase.jl")));'
 	julia --startup-file=no --project=docs -e 'using Pkg; Pkg.develop(PackageSpec(path=joinpath(Pkg.devdir(), "ExponentialFamily.jl")));'
@@ -85,7 +57,7 @@ test: ## Run tests, use dev=true to use `dev-ed` version of core packages
 devtest: ## Alias for the `make test dev=true ...`
 	julia -e 'ENV["USE_DEV"]="true"; import Pkg; Pkg.activate("."); Pkg.test()'	
 
-clean: ## Clean documentation build, precompiled examples, benchmark output from tests
+clean: ## Clean documentation build, benchmark output from tests
 	$(foreach file, $(ALL_TMP_FILES), $(RM) $(file))
 
 help:  ## Display this help

README.md

@@ -1,10 +1,9 @@
-
 ![](docs/src/assets/biglogo-blacktheme.svg?raw=true&sanitize=true)
 
 [![Official page](https://img.shields.io/badge/official%20page%20-RxInfer-blue)](https://reactivebayes.github.io/rxinfer-website/)
 [![Stable](https://img.shields.io/badge/docs-stable-blue.svg)](https://reactivebayes.github.io/RxInfer.jl/stable/)
 [![Dev](https://img.shields.io/badge/docs-dev-blue.svg)](https://reactivebayes.github.io/RxInfer.jl/dev/)
-[![Examples](https://img.shields.io/badge/examples-RxInfer-brightgreen)](https://reactivebayes.github.io/RxInfer.jl/stable/examples/overview/)
+[![Examples](https://img.shields.io/badge/examples-RxInfer-brightgreen)](https://reactivebayes.github.io/RxInferExamples.jl/)
 [![Q&A](https://img.shields.io/badge/Q&A-RxInfer-orange)](https://github.com/reactivebayes/RxInfer.jl/discussions)
 [![Roadmap](https://img.shields.io/badge/roadmap-RxInfer-yellow)](#roadmap)
 [![Build Status](https://github.com/reactivebayes/RxInfer.jl/actions/workflows/CI.yml/badge.svg?branch=main)](https://github.com/reactivebayes/RxInfer.jl/actions/workflows/CI.yml?query=branch%3Amain)
@@ -66,7 +65,8 @@ For more information about `RxInfer.jl` please refer to the [documentation](http
 
 # Getting Started
 
-There are examples available to get you started in the `examples/` folder. Alternatively, preview the same examples in the [documentation](https://reactivebayes.github.io/RxInfer.jl/stable/examples/overview/).
+> [!NOTE]
+> There are examples available to get you started in the [RxInferExamples.jl](https://reactivebayes.github.io/RxInferExamples.jl/) repository.
 
 ### Coin flip simulation
 
@@ -182,7 +182,7 @@ The `RxInfer` framework consists of three *core* packages developed by [Reactive
 
 # Where to go next?
 
-There are a set of [examples](https://reactivebayes.github.io/RxInfer.jl/stable/examples/overview/) available in `RxInfer` repository that demonstrate the more advanced features of the package. Alternatively, you can head to the [documentation](https://reactivebayes.github.io/RxInfer.jl/stable/) that provides more detailed information of how to use `RxInfer` to specify more complex probabilistic models.
+There are a set of [examples](https://reactivebayes.github.io/RxInferExamples.jl/) available in the `RxInferExamples.jl` repository that demonstrate the more advanced features of the package. Alternatively, you can head to the [documentation](https://reactivebayes.github.io/RxInfer.jl/stable/) that provides more detailed information of how to use `RxInfer` to specify more complex probabilistic models.
 
 
 # Join Our Community and Contribute to RxInfer

docs/.gitignore

@@ -1,4 +1 @@
-# Use `RxInfer.jl/examples` folder (see `.meta.jl`)
-Manifest.toml
-src/examples
-src/assets/examples
+Manifest.toml

docs/make.jl

@@ -8,84 +8,6 @@ ENV["GKSwstype"] = "100"
 
 DocMeta.setdocmeta!(RxInfer, :DocTestSetup, :(using RxInfer); recursive = true)
 
-# This must be auto-generated with `make examples`
-ExamplesPath = joinpath(@__DIR__, "src", "examples")
-ExamplesOverviewPath = joinpath(ExamplesPath, "overview.md")
-ExamplesMeta = include(joinpath(@__DIR__, "..", "examples", ".meta.jl"))
-
-ExamplesCategories = ExamplesMeta[:categories]
-ExamplesCategories = ExamplesCategories[setdiff(keys(ExamplesCategories), [:hidden_examples])]
-
-ExamplesCategoriesOverviewPaths = map(collect(pairs(ExamplesCategories))) do (label, _)
-    return joinpath(ExamplesPath, string(label), "overview.md")
-end
-
-Examples = map(filter(example -> !isequal(example[:category], :hidden_examples), ExamplesMeta[:examples])) do examplemeta
-    filename = examplemeta.filename
-    category = examplemeta.category
-    mdpath = replace(filename, ".ipynb" => ".md")
-    title = examplemeta.title
-
-    fullpath = joinpath(ExamplesPath, string(category), mdpath)
-    shortpath = joinpath("examples", string(category), mdpath)
-
-    # We use `fullpath` to check if the file exists
-    # We use `shortpath` to make a page reference in the left panel in the documentation
-    return title => (fullpath, shortpath, category)
-end
-
-if !isdir(ExamplesPath)
-    mkpath(ExamplesPath)
-end
-
-# Check if some examples are missing from the build
-# The `isfile` check needs only the full path, so we ignore the short path
-ExistingExamples = filter(Examples) do (title, info)
-    fullpath, _, _ = info
-    exists = isfile(fullpath)
-    if !exists
-        @warn "Example at path $(fullpath) does not exist. Skipping."
-    end
-    return exists
-end
-
-# Create an array of pages for each category
-ExamplesCategoriesPages = map(collect(pairs(ExamplesCategories))) do (label, category)
-    return label => (title = category.title, pages = ["Overview" => joinpath("examples", string(label), "overview.md")])
-end |> NamedTuple
-
-# The `pages` argument in the `makedocs` needs only a short path, so we ignore the full path
-foreach(ExistingExamples) do (title, info)
-    _, shortpath, category = info
-    push!(ExamplesCategoriesPages[category].pages, title => shortpath)
-end
-
-if length(Examples) !== length(ExistingExamples)
-    @warn "Some examples were not found. Use the `make examples` command to generate all examples."
-end
-
-# Check if the main `overview.md` file exists + sub categories `overview.md` files
-foreach(vcat(ExamplesOverviewPath, ExamplesCategoriesOverviewPaths)) do path
-    if !isfile(path)
-        @warn "`$(path)` does not exist. Generating an empty overview. Use the `make examples` command to generate the overview and all examples."
-        mkpath(dirname(path))
-        open(path, "w") do f
-            write(
-                f,
-                """
-       $(isequal(path, ExamplesOverviewPath) ? "# [Examples overview](@id examples-overview)" : "")
-       The overview is missing. Use the `make examples` command to generate the overview and all examples.
-       """
-            )
-        end
-    end
-end
-
-# Generate the final list of examples for each sub-category
-ExamplesPages = map(collect(pairs(ExamplesCategoriesPages))) do (label, info)
-    return info.title => info.pages
-end
-
 draft = get(ENV, "DOCS_DRAFT", "false") == "true"
 
 makedocs(;
@@ -128,11 +50,7 @@ makedocs(;
             "Functional form constraints" => "library/functional-forms.md",
             "Exported methods" => "library/exported-methods.md"
         ],
-        "Examples" => [
-            "Overview" => "examples/overview.md", # This must be auto-generated with `make examples`
-            ExamplesPages...,
-            "Contribute with examples" => "contributing/examples.md"
-        ],
+        "Examples" => "examples/overview.md",
         "Contributing" => [
             "Contribution guide" => "contributing/guide.md",
             "Contribution guidelines" => "contributing/guidelines.md",

docs/src/assets/header.js

@@ -33,7 +33,7 @@ window.onload = function() {
                     { title: "Home", link: "http://www.rxinfer.ml", icon: [ "fas", "fa-diagram-project" ] },
                     { title: "Get Started", link: "https://reactivebayes.github.io/RxInfer.jl/stable/manuals/getting-started/", icon: [ "fas", "fa-person-chalkboard" ] },
                     { title: "Documentation", link: "https://reactivebayes.github.io/RxInfer.jl/stable/", icon: [ "fas", "fa-book" ] },
-                    { title: "Examples", link: "https://reactivebayes.github.io/RxInfer.jl/stable/examples/overview/", icon: [ "fas", "fa-laptop-code" ] },
+                    { title: "Examples", link: "https://reactivebayes.github.io/RxInferExamples.jl/", icon: [ "fas", "fa-laptop-code" ] },
                     { title: "Papers", link: "https://biaslab.github.io/publication/", icon: [ "far", "fa-book-open" ] },
                     { title: "Team", link: "https://github.com/orgs/ReactiveBayes/people", icon: [ "fas", "fa-people-group" ] },
                     { title: "Discussions", link: "https://github.com/orgs/ReactiveBayes/discussions", icon: [ "far", "fa-comment" ] },
@@ -81,18 +81,5 @@ window.onload = function() {
     const documenterTarget = document.querySelector('#documenter');
 
     documenterTarget.parentNode.insertBefore(header, documenterTarget);
-
-    // Edit broken links in the examples, see issue #70
-    const editOnGithubLinkTarget = document.querySelector('.docs-edit-link');
-
-    if (editOnGithubLinkTarget) {
-        const link = editOnGithubLinkTarget.href;
-        if (link.includes('docs/src/examples')) {
-            const fixedLink = link.replace('docs/src/', '').replace('.md', '.ipynb');
-            editOnGithubLinkTarget.href = fixedLink;
-            console.log('Fixed link for the example: ', fixedLink)
-        }
-    }
-
 }
 

docs/src/contributing/examples.md

@@ -1,11 +1,14 @@
 # [Contribute with examples](@id examples)
 
-We welcome examples from the community that showcase RxInfer.jl in action! Whether you're working in machine learning, signal processing, robotics, computational biology, or any other domain - your contributions help others learn and explore probabilistic modeling with RxInfer.jl.
+The examples for RxInfer.jl are now maintained in a dedicated repository at [RxInferExamples.jl](https://reactivebayes.github.io/RxInferExamples.jl/). Please visit the examples repository to:
+- Browse existing examples
+- Learn how to contribute your own examples
+- Get started with RxInfer.jl
 
 ## Featured Examples
 
 - **Active Inference with RxInfer.jl** - Dive into the realm of Active Inference guided by [Kobus Esterhuysen](https://www.linkedin.com/in/kobusesterhuysen/) at [Learnable Loop](https://learnableloop.com/#category=RxInfer).
 - **Tutorial Series on RxInfer.jl** - Explore a series of engaging tutorial videos on RxInfer.jl's functionalities, presented by [@doggotodjl](https://www.youtube.com/@doggodotjl/search?query=RxInfer).
 
 !!! note 
-    If you're interested in contributing an example, we'd love to hear from you! Please initiate an issue or start a new discussion on our [GitHub repository](https://github.com/reactivebayes/RxInfer.jl) to get involved. The example notebook must follow a specific structure, which is described in the [Contribute to the examples](@ref contributing-new-example) section.
+    If you're interested in contributing an example, please visit the [RxInferExamples.jl](https://reactivebayes.github.io/RxInferExamples.jl/) repository. We welcome all contributions that help demonstrate the capabilities of RxInfer.jl!

docs/src/contributing/guidelines.md

@@ -45,10 +45,10 @@ We use the standard [GitHub Flow](https://guides.github.com/introduction/flow/)
 - Commit your contributions to your fork
 - Create a pull request on the `main` branch of the `RxInfer` repository.
 
-Before opening a pull request, ensure all tests pass without errors. Additionally, ensure all examples (found in the `/examples/` directory) run succesfully. 
+Before opening a pull request, ensure all tests pass without errors.
 
 !!! note
-    Use `make test`, `make examples` and `make docs` commands to verify that all tests, examples, and documentation build correctly. See the `Makefile` section below for detailed command descriptions.
+    Use `make test` and `make docs` commands to verify that all tests and documentation build correctly. See the `Makefile` section below for detailed command descriptions.
 
 ### Style conventions
 
@@ -97,8 +97,6 @@ make test
 - `make devtest`: Alias for the `make test dev=true ...`
 - `make docs`: Compile documentation
 - `make devdocs`: Same as `make docs`, but uses `dev-ed` versions of core packages
-- `make examples`: Run all examples and put them in the `docs/` folder if successfull 
-- `make devexamples`: Same as `make examples`, but uses `dev-ed` versions of core packages
 - `make lint`: Check codestyle
 - `make format`: Check and fix codestyle