diff --git a/.github/CONTRIBUTING.md b/.github/CONTRIBUTING.md index cf0a29c..e8ef0f9 100644 --- a/.github/CONTRIBUTING.md +++ b/.github/CONTRIBUTING.md @@ -2,6 +2,14 @@ Thank you for your interest in contributing to Fugue! This document provides guidelines for contributing to the project. +## Community + +- **Discord**: Join our [Discord server](https://discord.gg/QAcF7Nwr) +- **Issues & Bugs**: Open an [issue](https://github.com/alexnodeland/fugue/issues) with the `Bug Report` template. +- **Feature Requests**: Open an [issue](https://github.com/alexnodeland/fugue/issues) with the `Feature Request` template. +- **RFCs**: Open an [issue](https://github.com/alexnodeland/fugue/issues) with the `RFC` template. +- **Zotero**: Joing our [Zotero group](https://www.zotero.org/groups/6138134/fugue) + ## Quick Start ```bash diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml index 4a201dd..36b7602 100644 --- a/.github/workflows/docs.yml +++ b/.github/workflows/docs.yml @@ -30,27 +30,52 @@ jobs: ~/.cargo/registry/index/ ~/.cargo/registry/cache/ ~/.cargo/git/db/ - key: ${{ runner.os }}-cargo-mdbook-${{ hashFiles('**/Cargo.lock') }} + target/ + key: ${{ runner.os }}-cargo-${{ hashFiles('**/Cargo.lock') }} restore-keys: | - ${{ runner.os }}-cargo-mdbook- + ${{ runner.os }}-cargo- - name: Install mdBook and plugins run: | + # Check if tools are installed with correct major.minor version + install_if_needed() { + local tool=$1 + local major_minor=$2 + local cargo_version=$3 + + if command -v $tool &> /dev/null; then + local current_version=$($tool --version | grep -oE 'v[0-9]+\.[0-9]+' | head -1) + if [[ "$current_version" =~ v$major_minor ]]; then + echo "$tool $current_version already installed and compatible, skipping" + return + else + echo "$tool $current_version found but incompatible, updating to $cargo_version" + fi + else + echo "Installing $tool $cargo_version" + fi + + cargo install $tool --vers "$cargo_version" --locked --force + } + # Install mdBook with optimizations - cargo install mdbook \ - --no-default-features \ - --features search \ - --vers "^0.4" \ - --locked \ - --force + install_if_needed mdbook "0\.4" "^0.4" # Install plugins - cargo install mdbook-admonish --vers "^1.18" --locked --force - cargo install mdbook-mermaid --vers "^0.14" --locked --force - cargo install mdbook-toc --vers "^0.14" --locked --force - cargo install mdbook-katex --vers "^0.9" --locked --force + install_if_needed mdbook-admonish "1\." "^1.18" + install_if_needed mdbook-mermaid "0\.14" "^0.14" + install_if_needed mdbook-toc "0\.14" "^0.14" + install_if_needed mdbook-katex "0\.9" "^0.9" # Note: linkcheck skipped due to issues with LaTeX math syntax + - name: Cache mdBook build + uses: actions/cache@v4 + with: + path: docs/book + key: ${{ runner.os }}-mdbook-${{ hashFiles('docs/**/*.md', 'docs/book.toml') }} + restore-keys: | + ${{ runner.os }}-mdbook- + - name: Build documentation (validates structure) run: | cd docs @@ -71,6 +96,13 @@ jobs: # Test the library's rustdoc examples cargo test --doc + - name: Upload built documentation + uses: actions/upload-artifact@v4 + with: + name: built-docs + path: docs/book + retention-days: 1 + # Job to build and deploy (only on main branch) build-deploy: runs-on: ubuntu-latest @@ -85,44 +117,11 @@ jobs: url: ${{ steps.deployment.outputs.page_url }} steps: - - name: Checkout repository - uses: actions/checkout@v4 - - - name: Install Rust toolchain - uses: dtolnay/rust-toolchain@stable - - - name: Cache Cargo registry and target - uses: actions/cache@v4 + - name: Download built documentation + uses: actions/download-artifact@v4 with: - path: | - ~/.cargo/bin/ - ~/.cargo/registry/index/ - ~/.cargo/registry/cache/ - ~/.cargo/git/db/ - key: ${{ runner.os }}-cargo-mdbook-${{ hashFiles('**/Cargo.lock') }} - restore-keys: | - ${{ runner.os }}-cargo-mdbook- - - - name: Install mdBook and plugins - run: | - # Install mdBook with optimizations - cargo install mdbook \ - --no-default-features \ - --features search \ - --vers "^0.4" \ - --locked \ - --force - - # Install plugins with version constraints - cargo install mdbook-admonish --vers "^1.18" --locked --force - cargo install mdbook-mermaid --vers "^0.14" --locked --force - cargo install mdbook-toc --vers "^0.14" --locked --force - cargo install mdbook-katex --vers "^0.9" --locked --force - - - name: Build documentation - run: | - cd docs - mdbook build + name: built-docs + path: docs/book - name: Setup Pages uses: actions/configure-pages@v5 diff --git a/README.md b/README.md index 3e7c347..bd99385 100644 --- a/README.md +++ b/README.md @@ -15,6 +15,8 @@ [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT) [![CI](https://github.com/alexnodeland/fugue/actions/workflows/ci-develop.yml/badge.svg)](https://github.com/alexnodeland/fugue/actions/workflows/ci-develop.yml) [![codecov](https://codecov.io/gh/alexnodeland/fugue/branch/develop/graph/badge.svg?token=BDJ5OB6GOB)](https://codecov.io/gh/alexnodeland/fugue) +[![Downloads](https://img.shields.io/crates/d/fugue-ppl?logo=rust)](https://crates.io/crates/fugue-ppl) +[![Zotero](https://img.shields.io/badge/Zotero-Fugue-red?style=flat-square&logo=zotero&logoColor=CC2936)](https://www.zotero.org/groups/6138134/fugue/library) [![Discord](https://img.shields.io/discord/1412802057437712426?logo=discord&label=discord)](https://discord.gg/QAcF7Nwr) **Supported Rust:** 1.70+ • **Platforms:** Linux / macOS / Windows • **Crate:** [`fugue-ppl` on crates.io](https://crates.io/crates/fugue-ppl) @@ -78,6 +80,7 @@ let mu_values: Vec = samples.iter() - **[User Guide](https://fugue.run/)** - Comprehensive tutorials and examples - **[API Reference](https://docs.rs/fugue-ppl/latest/fugue/)** - Complete API documentation - **Examples** - See `examples/` directory +- **[References](https://www.zotero.org/groups/6138134/fugue/library)** - Zotero library for Fugue ## 🤝 Community @@ -122,3 +125,5 @@ If you use Fugue in your research, please cite: year = {2025} } ``` + +Or refer to the "Internal" collection in [Zotero](https://www.zotero.org/groups/6138134/fugue/library) to generate a bibliography. diff --git a/assets/fugue-logo.svg b/assets/fugue-logo.svg index cfe1987..81a184b 100644 --- a/assets/fugue-logo.svg +++ b/assets/fugue-logo.svg @@ -1,5 +1,5 @@ - + diff --git a/docs/src/fugue-logo.svg b/docs/src/fugue-logo.svg index cfe1987..81a184b 100644 --- a/docs/src/fugue-logo.svg +++ b/docs/src/fugue-logo.svg @@ -1,5 +1,5 @@ - + diff --git a/docs/src/home.md b/docs/src/home.md index d4f418b..23a3fc5 100644 --- a/docs/src/home.md +++ b/docs/src/home.md @@ -15,6 +15,9 @@ [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT) [![CI](https://github.com/alexnodeland/fugue/actions/workflows/ci-develop.yml/badge.svg)](https://github.com/alexnodeland/fugue/actions/workflows/ci-develop.yml) [![codecov](https://codecov.io/gh/alexnodeland/fugue/branch/develop/graph/badge.svg?token=BDJ5OB6GOB)](https://codecov.io/gh/alexnodeland/fugue) +[![Downloads](https://img.shields.io/crates/d/fugue-ppl?logo=rust)](https://crates.io/crates/fugue-ppl) +[![Zotero](https://img.shields.io/badge/Zotero-Fugue-red?style=flat-square&logo=zotero&logoColor=CC2936)](https://www.zotero.org/groups/6138134/fugue/library) +[![Discord](https://img.shields.io/discord/1412802057437712426?logo=discord&label=discord)](https://discord.gg/QAcF7Nwr) **Supported Rust:** 1.70+ • **Platforms:** Linux / macOS / Windows • **Crate:** [`fugue-ppl` on crates.io](https://crates.io/crates/fugue-ppl) @@ -22,9 +25,9 @@ --- -```admonish info title="👋 Welcome to the Fugue User Guide" +```admonish info title="👋 Welcome" -Fugue is a production-ready, monadic probabilistic programming library for Rust. Check out these resources to get started: +Check out these resources to get started: - [Getting Started](./getting-started/README.md) - Installation and first steps - [How-To Guides](./how-to/README.md) - Practical guides for common tasks @@ -54,4 +57,5 @@ fugue-ppl = "0.1.0" - [GitHub Repository](https://github.com/alexnodeland/fugue) - [API Reference](https://docs.rs/fugue-ppl) +- [Zotero](https://www.zotero.org/groups/6138134/fugue/library) ```