snakemake/ioutils/exists.py (1)

9-29: Consider adding type annotations to the exists function for clarity.

Adding type annotations to the exists function's parameter and return type can improve code readability and assist with static type checking.

Example:

def exists(path: str) -> bool:
    """Return True if the given file or directory exists.

    This function considers any storage arguments given to Snakemake.
    """
    # Function implementation remains the same...

snakemake/ioutils/rule_items_proxy.py (3)

52-73: Refactor to eliminate code duplication in _deferred_get method.

The conditional blocks handling self.name for "output", "input", "params", and "resources" are very similar. Consider refactoring by mapping self.name to the corresponding parameter name to reduce code duplication.

Example refactor:

def _deferred_get(self, key: Union[str, int], kind: KeyKind):
    if kind == KeyKind.ATTRIBUTE:

        def _get(item):
            return getattr(item, key)
    elif kind == KeyKind.ITEM:

        def _get(item):
            return item[key]
    else:
        raise ValueError("kind must be 'attribute' or 'item'")

    valid_names = {"output", "input", "params", "resources"}
    if self.name in valid_names:

        def inner(_wildcards, **kwargs):
            return _get(kwargs[self.name])
    else:
        raise ValueError(f"Unknown item type: {self.name}")

    return inner

---

73-74: Enhance error message for unknown item types.

When raising a ValueError for an unknown self.name, consider including the list of valid item types in the error message to aid debugging.

Example:

raise ValueError(f"Unknown item type: {self.name}. Valid types are 'output', 'input', 'params', 'resources'.")

---

29-75: Consider adding type annotations to class methods for clarity.

Adding type annotations to the methods in RuleItemProxy can improve code readability and assist with static type checking.

Example:

class RuleItemProxy:
    def __init__(self, name: str):
        self.name = name

    def __getattr__(self, name: str):
        return self._deferred_get(name, KeyKind.ATTRIBUTE)

    def __getitem__(self, key: Union[str, int]):
        return self._deferred_get(key, KeyKind.ITEM)

    def _deferred_get(self, key: Union[str, int], kind: KeyKind):
        # Method implementation...

snakemake/ioutils/branch.py (1)

5-62: Consider adding type annotations to the branch function for clarity.

Adding type annotations to the branch function's parameters and return type can improve code readability and assist with static type checking.

Example:

from typing import Any

def branch(
    condition: Union[Callable[[Any], Any], bool],
    then: Optional[Union[str, list[str], Callable]] = None,
    otherwise: Optional[Union[str, list[str], Callable]] = None,
    cases: Optional[Mapping[Any, Union[str, list[str], Callable]]] = None,
) -> Union[Callable, list[str]]:
    # Function implementation...

docs/snakefiles/rules.rst (1)

218-218: Add missing word for clarity in documentation

Insert "that" to improve the sentence: "Afterwards, we will further show a set of semantic helper functions that should increase readability and simplify code..."

Configuration used: CodeRabbit UI
Review profile: CHILL

apidocs/index.rst (1)

63-63: LGTM! Consider standardizing entry format.

The change improves clarity by providing a descriptive label for the internal API section. For consistency with other entries in the toctree (e.g., snakemake_api, snakemake_utils), consider using a similar naming pattern.

-    Internal API <api_reference/internal/modules>
+    snakemake_internal <api_reference/internal/modules>

snakemake/ioutils/subpath.py (1)

27-27: Address the TODO: Implement argument type checking for function parameters.

The TODO comment at line 27 suggests adding type checking for arguments. Implementing this will enhance error handling and ensure that users provide valid inputs to the subpath function.

Would you like assistance in creating a decorator or solution for argument type checking?

snakemake/api.py (1)

290-292: Consider refactoring decorators to reduce code duplication.

The decorators _no_dag and _no_exec perform similar functions by setting cores to 1 before method execution. You might consider creating a single parameterized decorator to handle both cases and reduce code duplication.

Example refactored decorator:

def _set_cores_to_one(attr_path):
    def decorator(method):
        @functools.wraps(method)
        def wrapper(self, *args, **kwargs):
            setattr(self, attr_path, 1)
            return method(self, *args, **kwargs)
        return wrapper
    return decorator

Applying the decorator:

@_set_cores_to_one("resource_settings.cores")
def lint(self, json: bool = False):
    # method body

@_set_cores_to_one("workflow_api.resource_settings.cores")
def generate_unit_tests(self, path: Path):
    # method body

Also applies to: 604-606

snakemake/ioutils/evaluate.py (1)

4-6: Enhance docstring with more details

Consider adding:

• Parameter description for expr
• Return value description
• Example usage
• Warning about security implications of eval()

tests/test_internals.py (1)

5-21: Enhance test coverage with error and edge cases

While the current tests cover the basic functionality well, consider adding tests for:

1. Error cases:
   • Invalid ancestor levels (negative or too large)
   • Invalid/malformed paths
2. Edge cases:
   • Empty paths
   • Absolute paths
   • Paths with special characters
   • Multiple suffix stripping

Would you like assistance in generating these additional test cases?

tests/tests.py (1)

249-251: Consider improving test documentation and assertions.

The test function would benefit from:

1. A docstring explaining the purpose and expected behavior of the subpath functionality being tested
2. Specific assertions or validations to verify the correct behavior

-def test_subpath():
-    run(dpath("test_subpath"))
+def test_subpath():
+    """Test the subpath functionality.
+    
+    Verifies that the subpath utility correctly processes paths according to
+    the specified parameters.
+    """
+    run(dpath("test_subpath"))
+    # Consider adding specific assertions here

Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro

#!/bin/bash
# Description: Verify the existence of test data directory and its contents

# Check if the test directory exists
fd -t d "test_subpath$"

# List contents of the test directory if found
fd . -t f "test_subpath"

#!/bin/bash
# Let's check the contents of the test_subpath directory
ls -la tests/test_subpath/

# Also check if there are any references to test_subpath in the test file
rg "test_subpath" tests/tests.py -B 2 -A 2

#!/bin/bash
# Let's check the contents of the Snakefile and expected-results directory
cat tests/test_subpath/Snakefile
ls -la tests/test_subpath/expected-results/

#!/bin/bash
# Let's check the contents of the results directory in expected-results
ls -R tests/test_subpath/expected-results/results/

snakemake/ioutils/branch.py (3)

5-27: Consider enhancing the docstring with parameter types and return value.

While the docstring is comprehensive in explaining the functionality, it could benefit from explicitly documenting:

• Parameter types and their constraints
• Return value type and possible values

Example enhancement:

 def branch(
     condition: Union[Callable, bool],
     then: Optional[Union[str, list[str], Callable]] = None,
     otherwise: Optional[Union[str, list[str], Callable]] = None,
     cases: Optional[Mapping] = None,
 ):
     """Branch based on a condition that is provided as a function pointer (i.e. a Callable)
     or a value.

     If then and optionally otherwise are specified, do the following:
     If the condition is (or evaluates to) True, return the value
     of the then parameter. Otherwise, return the value of the otherwise parameter.

     If cases is specified, do the following:
     Retrieve the value of the cases mapping using the return value of the condition
     (if it is a function), or the condition value itself as a key.

     The given condition function has to take wildcards as its only parameter.
     Similarly, then, otherwise and the values of the cases mapping can be such functions.

     If any such function is given to any of those arguments, this function returns a derived
     input function that will be evaluated once the wildcards are known.
+
+    Args:
+        condition: A boolean value or a callable that takes wildcards and returns a boolean
+        then: Value or callable to use when condition is True
+        otherwise: Value or callable to use when condition is False
+        cases: Mapping of condition results to values or callables
+
+    Returns:
+        Union[list[str], Callable]: Either a list of strings or a callable that returns such a list
+
+    Raises:
+        ValueError: If cases is used together with then or otherwise
+        KeyError: If the condition result is not found in cases
     """

---

29-37: Consider adding type hints to helper functions.

The helper functions are well-implemented but could benefit from type hints for better maintainability and IDE support.

-    def convert_none(value):
+    def convert_none(value: Optional[Union[str, list[str]]]) -> list[str]:
         return value or []

-    def handle_callable(value, wildcards):
+    def handle_callable(
+        value: Optional[Union[str, list[str], Callable]],
+        wildcards: Any
+    ) -> list[str]:
         if isinstance(value, Callable):
             return convert_none(value(wildcards))
         else:
             return convert_none(value)

---

52-65: Consider validating the cases parameter.

When cases is provided, it would be helpful to validate that it's not empty to prevent potential runtime errors.

     do_branch = do_branch_then_otherwise
     if cases is not None:
         if otherwise is not None or then is not None:
             raise ValueError("Cannot use cases together with then or otherwise.")
+        if not cases:
+            raise ValueError("Cases mapping cannot be empty")
         do_branch = do_branch_cases

Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro

docs/snakefiles/rules.rst (2)

551-569: Rule item access documentation needs clarification.

While the section explains the concept of rule item access, it could benefit from:

1. A more explicit example showing how to use the returned function
2. Clarification on when to use this pattern vs. direct access

Consider adding a complete example like:

rule process:
    input:
        "data/{sample}.txt"
    output:
        "results/{sample}.txt"
    resources:
        mem_mb=lambda wildcards, input: len(input) * 100

---

1113-1154: Plain Python rules section needs formatting improvements.

The section about shell command execution within Python rules needs better formatting:

1. Code blocks should be indented consistently
2. Shell command examples should show proper string formatting

Consider reformatting the code examples for better readability:

# Example of shell command in Python rule
shell("somecommand {output.somename}")

# Example of iterating over shell output
for line in shell("somecommand {output.somename}", iterable=True):
    # Process line
    pass

snakemake/ioutils/branch.py (4)

5-27: Enhance docstring with parameter descriptions and return type.

The docstring provides good functional description but could be improved by adding:

• Parameter descriptions with their types
• Return type and description
• Example usage

Consider adding:

"""
Parameters
----------
condition : Union[Callable, bool]
    The condition to evaluate, either a boolean or a callable that returns one
then : Optional[Union[str, list[str], Callable]], optional
    Value to return if condition is True
otherwise : Optional[Union[str, list[str], Callable]], optional
    Value to return if condition is False
cases : Optional[Mapping], optional
    Mapping of condition results to values

Returns
-------
Union[Callable, list]
    Either a callable (if any input is callable) or the evaluated result

Examples
--------
>>> branch(True, "a.txt", "b.txt")
["a.txt"]
>>> branch(lambda wc: wc.sample == "A", "a.txt", "b.txt")
<function>
"""

---

29-37: Add docstrings to helper functions.

The helper functions are well-implemented but lack documentation explaining their purpose and behavior.

Consider adding:

def convert_none(value):
    """Convert None to empty list, otherwise return the value.
    
    Parameters
    ----------
    value : Any
        Value to convert
        
    Returns
    -------
    Union[list, Any]
        Empty list if value is None, otherwise the original value
    """
    return value or []

def handle_callable(value, wildcards):
    """Handle both callable and non-callable values with wildcard support.
    
    Parameters
    ----------
    value : Union[Callable, Any]
        Value to handle
    wildcards : dict
        Wildcard values to pass to callable
        
    Returns
    -------
    Any
        Result of callable(wildcards) if value is callable, otherwise the value
    """
    if isinstance(value, Callable):
        return convert_none(value(wildcards))
    else:
        return convert_none(value)

---

44-51: Improve error handling in do_branch_cases.

While basic error handling exists, it could be enhanced to provide more context and better error messages.

Consider:

     def do_branch_cases(wildcards):
         res = handle_callable(condition, wildcards)
+        if not cases:
+            raise ValueError("Cases mapping cannot be empty")
         try:
             selected_case = cases[res]
         except KeyError:
-            raise KeyError(f"Key {res} not found in given cases of branch function")
+            raise KeyError(
+                f"Result '{res}' (type: {type(res).__name__}) not found in cases. "
+                f"Available cases: {list(cases.keys())}"
+            )
         return handle_callable(selected_case, wildcards)

🧰 Tools

🪛 Ruff (0.8.2)

49-49: Within an except clause, raise exceptions with raise ... from err or raise ... from None to distinguish them from errors in exception handling

(B904)

---

52-65: Add input validation for mutually exclusive parameters.

The validation of mutually exclusive parameters could be moved to the start of the function for early failure.

Consider:

 def branch(
     condition: Union[Callable, bool],
     then: Optional[Union[str, list[str], Callable]] = None,
     otherwise: Optional[Union[str, list[str], Callable]] = None,
     cases: Optional[Mapping] = None,
 ):
+    # Validate mutually exclusive parameters
+    if cases is not None and (then is not None or otherwise is not None):
+        raise ValueError("Cannot use cases together with then or otherwise.")
+    if cases is None and then is None:
+        raise ValueError("Must provide either cases or then parameter.")
+
     def convert_none(value):
         return value or []
     # ... rest of the function ...
-    do_branch = do_branch_then_otherwise
-    if cases is not None:
-        if otherwise is not None or then is not None:
-            raise ValueError("Cannot use cases together with then or otherwise.")
-        do_branch = do_branch_cases
+    do_branch = do_branch_cases if cases is not None else do_branch_then_otherwise

.github/workflows/docs.yml (3)

3-12: Consider adding path filters to optimize workflow triggers.

The workflow could be more efficient by only running when documentation-related files change.

 on:
   push:
     branches:
       - main
+    paths:
+      - 'docs/**'
+      - 'apidocs/**'
+      - '.github/workflows/docs.yml'
   pull_request:
+    paths:
+      - 'docs/**'
+      - 'apidocs/**'
+      - '.github/workflows/docs.yml'

---

23-23: Fix YAML formatting issues.

There are some minor formatting issues:

• Trailing spaces on lines 23 and 38
• Missing newline at end of file

       - name: Setup doc dependencies
         run: |
-          pip install -f docs/requirements.txt      
+          pip install -f docs/requirements.txt
       
       - name: Setup doc dependencies
         run: |
-          pip install -f apidocs/requirements.txt      
+          pip install -f apidocs/requirements.txt
           pip install -e .
       
       - name: Build docs
         run: |
           cd apidocs
-          make html
\ No newline at end of file
+          make html
+

Also applies to: 38-38, 42-42

🧰 Tools

🪛 yamllint (1.35.1)

[error] 23-23: trailing spaces

(trailing-spaces)

---

1-42: Consider enhancing the workflow with artifacts and preview deployments.

To improve the documentation workflow:

1. Upload built documentation as artifacts for verification
2. Consider deploying documentation previews for PRs using GitHub Pages or similar

Example implementation for artifacts:

      - name: Upload documentation artifact
        uses: actions/upload-artifact@v3
        with:
          name: documentation
          path: |
            docs/_build/html/
            apidocs/_build/html/

🧰 Tools

🪛 yamllint (1.35.1)

[error] 23-23: trailing spaces

(trailing-spaces)

---

[error] 38-38: trailing spaces

(trailing-spaces)

---

[error] 42-42: no new line character at the end of file

(new-line-at-end-of-file)

Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro

docs/snakefiles/rules.rst (3)

551-569: Documentation needs examples for rule item access.

While the section explains the concept of rule item access well, it would benefit from concrete examples showing:

1. How to access different rule items (input, output, resources, etc.)
2. Common use cases and patterns

Consider adding examples like:

# Example accessing input files
rule process:
    input:
        "input.txt"
    output:
        "output.txt"
    params:
        threshold=lambda wildcards, input: get_threshold(input[0])
    shell:
        "process {input} {output}"

# Example accessing resources
rule analyze:
    input:
        "data.txt"
    output:
        "results.txt"
    resources:
        mem_mb=1000
    params:
        mem=lambda wildcards, resources: resources.mem_mb / 1000
    shell:
        "analyze --memory {params.mem}G {input} {output}"

---

570-605: Documentation needs clarification on sub-path access behavior.

The sub-path access section would benefit from:

1. A note about path normalization behavior
2. Examples of error handling when paths don't match expected patterns
3. Clarification on behavior with absolute vs relative paths

---

3088-3115: Important note about shell command placeholders needs emphasis.

The note about escaping placeholders in shell commands is crucial for preventing errors, but it could be more prominent. Consider:

1. Adding a warning box or stronger visual emphasis
2. Including examples of common mistakes

Add examples like:

# Wrong - will try to evaluate {input}
rule wrong:
    shell:
        "echo 'Using {input} for processing' > log.txt"

# Correct - escapes {input}
rule correct:
    shell:
        "echo 'Using {{input}} for processing' > log.txt"

Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro

.github/workflows/docs.yml (1)

33-51: 🛠️ Refactor suggestion

Apply the same enhancements to the apidocs job.

For consistency with the docs job, apply similar improvements:

Apply these changes:

  apidocs:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      
      - uses: actions/setup-python@v4
        with:
-         python-version: '3.x'
+         python-version: '3.11'  # Specify exact version for consistency
+         cache: 'pip'
      
      - name: Setup doc dependencies
        run: |
          python -m pip install --upgrade pip
          pip install -r apidocs/requirements.txt
          pip install -e .
      
      - name: Build docs
        run: |
          cd apidocs
          make html SPHINXOPTS="-W --keep-going -n"
+
+      - name: Upload API documentation
+        uses: actions/upload-artifact@v4
+        with:
+          name: apidocs-html
+          path: apidocs/_build/html/
+

🧰 Tools

🪛 actionlint (1.7.4)

38-38: the runner of "actions/setup-python@v4" action is too old to run on GitHub Actions. update the action's version to fix this issue

(action)

🪛 yamllint (1.35.1)

[error] 37-37: trailing spaces

(trailing-spaces)

---

[error] 47-47: trailing spaces

(trailing-spaces)

---

[error] 51-51: no new line character at the end of file

(new-line-at-end-of-file)

.github/workflows/docs.yml (1)

1-51: Fix minor formatting issues.

There are some formatting issues in the file:

1. Remove trailing spaces on lines 19, 28, 37, and 47
2. Add a newline at the end of the file

These can be automatically fixed by running:

#!/bin/bash
# Remove trailing spaces and ensure newline at EOF
sed -i 's/[[:space:]]*$//' .github/workflows/docs.yml
echo >> .github/workflows/docs.yml

🧰 Tools

🪛 actionlint (1.7.4)

20-20: the runner of "actions/setup-python@v4" action is too old to run on GitHub Actions. update the action's version to fix this issue

(action)

---

38-38: the runner of "actions/setup-python@v4" action is too old to run on GitHub Actions. update the action's version to fix this issue

(action)

🪛 yamllint (1.35.1)

[error] 19-19: trailing spaces

(trailing-spaces)

---

[error] 28-28: trailing spaces

(trailing-spaces)

---

[error] 37-37: trailing spaces

(trailing-spaces)

---

[error] 47-47: trailing spaces

(trailing-spaces)

---

[error] 51-51: no new line character at the end of file

(new-line-at-end-of-file)

Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro

.github/workflows/docs.yml (2)

14-32: 🛠️ Refactor suggestion

Enhance the docs job configuration.

The following improvements are recommended:

Apply these changes:

  docs:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
-      
+
      - uses: actions/setup-python@v4
        with:
-         python-version: '3.x'
+         python-version: '3.11'  # Specify exact version for consistency
+         cache: 'pip'

      - name: Setup doc dependencies
        run: |
          python -m pip install --upgrade pip
          pip install -r docs/requirements.txt
-      
+
      - name: Build docs
        run: |
          cd docs
          make html SPHINXOPTS="-W --keep-going -n"
+
+      - name: Upload documentation
+        uses: actions/upload-artifact@v4
+        with:
+          name: docs-html
+          path: docs/_build/html/

🧰 Tools

🪛 actionlint (1.7.4)

20-20: the runner of "actions/setup-python@v4" action is too old to run on GitHub Actions. update the action's version to fix this issue

(action)

🪛 yamllint (1.35.1)

[error] 19-19: trailing spaces

(trailing-spaces)

---

[error] 28-28: trailing spaces

(trailing-spaces)

---

33-51: 🛠️ Refactor suggestion

Apply similar improvements to the apidocs job.

The apidocs job needs the same enhancements as the docs job, plus proper file ending.

Apply these changes:

  apidocs:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
-      
+
      - uses: actions/setup-python@v4
        with:
-         python-version: '3.x'
+         python-version: '3.11'  # Specify exact version for consistency
+         cache: 'pip'

      - name: Setup doc dependencies
        run: |
          python -m pip install --upgrade pip
          pip install -r apidocs/requirements.txt
          pip install -e .
-      
+
      - name: Build docs
        run: |
          cd apidocs
          make html SPHINXOPTS="-W --keep-going -n"
+
+      - name: Upload API documentation
+        uses: actions/upload-artifact@v4
+        with:
+          name: apidocs-html
+          path: apidocs/_build/html/
+

🧰 Tools

🪛 actionlint (1.7.4)

38-38: the runner of "actions/setup-python@v4" action is too old to run on GitHub Actions. update the action's version to fix this issue

(action)

🪛 yamllint (1.35.1)

[error] 37-37: trailing spaces

(trailing-spaces)

---

[error] 47-47: trailing spaces

(trailing-spaces)

---

[error] 51-51: no new line character at the end of file

(new-line-at-end-of-file)

docs/snakefiles/rules.rst (3)

12-24: Improve rule example clarity and documentation.

The example rule definition could be enhanced with more descriptive variable names and additional comments explaining the purpose of each section.

-    rule myrule:
+    rule process_data:
         input:
-            "path/to/inputfile",
-            "path/to/other/inputfile",
+            # Primary input file
+            "data/input/sample.txt",
+            # Reference data
+            "data/reference/ref.txt",
         output:
-            "path/to/outputfile",
-            "path/to/another/outputfile",
+            # Main result file
+            "results/processed.txt",
+            # Additional metrics
+            "results/metrics.txt",
         shell:
-            "somecommand {input} {output}"
+            # Process input data and generate results
+            "process_data --input {input} --output {output}"

---

551-569: Enhance rule item access documentation with examples.

The rule item access documentation would benefit from concrete examples showing different access patterns.

Add examples like:

# Example 1: Accessing input files by name
rule process:
    input:
        reads="data/{sample}.fastq",
        reference="ref/genome.fa"
    params:
        # Access named input file
        def get_reads(wildcards, input):
            return input.reads

# Example 2: Accessing input files by index
rule merge:
    input:
        "part1.txt",
        "part2.txt"
    params:
        # Access input file by index
        def get_first(wildcards, input):
            return input[0]

---

3088-3115: Improve procedural rule definition example.

The procedural rule definition example could be enhanced with better error handling and validation.

 for tool in ["bcftools", "freebayes"]:
+    # Validate tool existence and version
+    tool_version = {
+        "bcftools": "1.9",
+        "freebayes": "1.3.2"
+    }
     rule:
         name: 
             f"call_variants_{tool}"
         input:
             f"path/to/{tool}/inputfile"
         output:
             f"path/to/{tool}/outputfile"
+        conda:
+            # Ensure consistent tool versions
+            f"envs/{tool}.yaml"
         shell:
-            f"{tool} {{input}} > {{output}}"
+            # Add version check and error handling
+            f"set -e; "
+            f"{tool} --version | grep {tool_version[tool]}; "
+            f"{tool} {{input}} > {{output}} || {{ echo '{tool} failed'; exit 1; }}"

Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro

#!/bin/bash
# Check if these are indeed report files that should be excluded
fd -t f "cars\.rst|horsepower_vs_mpg\.rst|workflow\.rst" -x file {}

#!/bin/bash
# Let's check if these files exist and examine their content
fd -t f "cars\.rst|horsepower_vs_mpg\.rst|workflow\.rst"

# Also check for any related generation scripts or patterns
rg -l "cars\.rst|horsepower_vs_mpg\.rst|workflow\.rst" -g "!docs/conf.py"

#!/bin/bash
# Let's check the content of the Snakefile to see if these are generated files
cat "docs/tutorial/interaction_visualization_reporting/workdir/workflow/Snakefile"

# Also check the tutorial content for context
head -n 50 "docs/tutorial/interaction_visualization_reporting/tutorial.rst"

      - name: Build docs
        run: |
          cd docs
          make html SPHINXOPTS="-W --keep-going -n"
+         make linkcheck  # Verify external links

      - name: Build docs
        run: |
          cd docs
          make html SPHINXOPTS="-W --keep-going -n"
+         make linkcheck

      - name: Build docs
        run: |
          cd apidocs
          make html SPHINXOPTS="-W --keep-going -n"
+         make linkcheck

#!/bin/bash
# Description: Verify documentation requirements and structure

# Check if requirements files exist and are not empty
if [ ! -s docs/requirements.txt ] || [ ! -s apidocs/requirements.txt ]; then
  echo "Error: Documentation requirements files are missing or empty"
  exit 1
fi

# Check for essential Sphinx configuration
for dir in docs apidocs; do
  if [ ! -f "$dir/conf.py" ]; then
    echo "Error: Missing conf.py in $dir"
    exit 1
  fi
done

# Check for index files
for dir in docs apidocs; do
  if [ ! -f "$dir/index.rst" ] && [ ! -f "$dir/index.md" ]; then
    echo "Error: Missing index file in $dir"
    exit 1
  fi
done

#!/bin/bash
# Let's verify if the documentation structure exists and check its contents
echo "=== Checking requirements files ==="
for dir in docs apidocs; do
  echo "Contents of $dir/requirements.txt:"
  if [ -f "$dir/requirements.txt" ]; then
    cat "$dir/requirements.txt"
  else 
    echo "File not found"
  fi
done

echo -e "\n=== Checking Sphinx configuration ==="
for dir in docs apidocs; do
  echo "Checking $dir/conf.py:"
  if [ -f "$dir/conf.py" ]; then
    # Look for linkcheck configuration
    echo "Linkcheck settings in $dir/conf.py:"
    grep -A 5 "linkcheck_" "$dir/conf.py" || echo "No linkcheck settings found"
  else
    echo "File not found"
  fi
done

echo -e "\n=== Checking Makefile targets ==="
for dir in docs apidocs; do
  echo "Available make targets in $dir/Makefile:"
  if [ -f "$dir/Makefile" ]; then
    grep "^[a-zA-Z].*:" "$dir/Makefile"
  else
    echo "Makefile not found"
  fi
done

apidocs/requirements.txt (1)

12-14: Add version constraints for new dependencies.

The newly added packages lack version constraints, which could lead to compatibility issues in the future. Consider adding specific version constraints:

-snakemake-interface-storage-plugins
-flask
-pytest
+snakemake-interface-storage-plugins>=0.1.0
+flask>=2.0.0
+pytest>=7.0.0

Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro

.github/workflows/docs.yml (1)

1-63: Fix formatting issues.

The YAML file has several formatting issues:

• Multiple trailing spaces (lines 19, 28, 38, 43, 53)
• Missing newline at end of file

Consider using an editor with YAML support or running yamllint locally to catch these issues before committing.

🧰 Tools

🪛 actionlint (1.7.4)

20-20: the runner of "actions/setup-python@v4" action is too old to run on GitHub Actions. update the action's version to fix this issue

(action)

---

44-44: the runner of "actions/setup-python@v4" action is too old to run on GitHub Actions. update the action's version to fix this issue

(action)

🪛 yamllint (1.35.1)

[error] 19-19: trailing spaces

(trailing-spaces)

---

[error] 28-28: trailing spaces

(trailing-spaces)

---

[error] 38-38: trailing spaces

(trailing-spaces)

---

[error] 43-43: trailing spaces

(trailing-spaces)

---

[error] 53-53: trailing spaces

(trailing-spaces)

---

[error] 63-63: no new line character at the end of file

(new-line-at-end-of-file)

Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro

  - uses: actions/setup-python@v4
    with:
-     python-version: '3.x'
+     python-version: '3.11'  # Specify exact version for consistency
+     cache: 'pip'

.github/workflows/docs.yml (1)

63-63: Add newline at end of file.

Add a newline character at the end of the file to follow YAML best practices.

Apply this change:

-          path: apidocs/_build/html/
+          path: apidocs/_build/html/
+

🧰 Tools

🪛 yamllint (1.35.1)

[error] 63-63: no new line character at the end of file

(new-line-at-end-of-file)

Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro

  docs:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      
      - uses: actions/setup-python@v4
        with:
-         python-version: '3.x'
+         python-version: '3.11'  # Specify exact version for consistency
+         cache: 'pip'

-         make html SPHINXOPTS="--keep-going -n"
+         make html SPHINXOPTS="-W --keep-going -n"