Merge pull request #195 from cgat-developers/AC-document

Ac document

.github/workflows/cgatcore_python.yml

@@ -81,9 +81,15 @@ jobs:
 
       - name: Install MkDocs and Dependencies
         run: |
-          pip install mkdocs mkdocs-material mkdocstrings[python]
+          pip install mkdocs \
+                    mkdocs-material \
+                    mkdocstrings[python] \
+                    pymdown-extensions \
+                    mkdocs-material[imaging]
 
       - name: Build and Deploy MkDocs Site
-        run: mkdocs gh-deploy --force --clean
+        run: |
+          mkdocs build
+          mkdocs gh-deploy --force --clean
         env:
           GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}

docs/getting_started/examples.md

@@ -228,13 +228,13 @@ When running the pipeline, make sure to specify `--no-cluster` as a command line
 - **Logs**: Check the log files generated during the pipeline run for detailed error messages.
 - **Support**: For further assistance, refer to the [CGAT-core documentation](https://cgat-developers.github.io/cgat-core/) or raise an issue on our [GitHub repository](https://github.com/cgat-developers/cgat-core/issues).
 
-## CGAT-core Examples
+## CGAT-core Examples {#cgat-core-examples}
 
 This guide provides practical examples of CGAT-core pipelines for various use cases, from basic file processing to complex genomics workflows.
 
-## Quick Start Examples
+## Quick Start Examples {#quick-start-examples}
 
-### Hello World Pipeline
+### Hello World Pipeline {#hello-world-pipeline}
 
 ```python
 """hello_world.py - Simple CGAT pipeline example
@@ -271,7 +271,7 @@ if __name__ == "__main__":
     sys.exit(P.main(sys.argv))
 ```
 
-### Configuration Example
+### Configuration Example {#configuration-example}
 
 ```yaml
 # pipeline.yml
@@ -287,9 +287,9 @@ cluster:
     memory_default: 1G
 ```
 
-## Real-World Examples
+## Real-World Examples {#real-world-examples}
 
-### 1. Genomics Pipeline
+### 1. Genomics Pipeline {#genomics-pipeline}
 
 This example demonstrates a typical RNA-seq analysis pipeline:
 
@@ -380,7 +380,7 @@ if __name__ == "__main__":
     sys.exit(P.main(sys.argv))
 ```
 
-### 2. Data Processing Pipeline
+### 2. Data Processing Pipeline {#data-processing-pipeline}
 
 Example of a data processing pipeline with S3 integration:
 
@@ -455,7 +455,7 @@ if __name__ == "__main__":
     sys.exit(P.main(sys.argv))
 ```
 
-### 3. Image Processing Pipeline
+### 3. Image Processing Pipeline {#image-processing-pipeline}
 
 Example of an image processing pipeline:
 
@@ -522,9 +522,9 @@ if __name__ == "__main__":
     sys.exit(P.main(sys.argv))
 ```
 
-## Best Practices
+## Best Practices {#best-practices}
 
-### 1. Resource Management
+### 1. Resource Management {#resource-management}
 
 ```python
 @transform("*.bam", suffix(".bam"), ".sorted.bam")
@@ -550,7 +550,7 @@ def sort_bam(infile, outfile):
     P.run(statement)
 ```
 
-### 2. Error Handling
+### 2. Error Handling {#error-handling}
 
 ```python
 @transform("*.txt", suffix(".txt"), ".processed")
@@ -571,7 +571,7 @@ def robust_processing(infile, outfile):
         P.cleanup_tmpdir()
 ```
 
-### 3. Configuration Management
+### 3. Configuration Management {#configuration-management}
 
 ```yaml
 # pipeline.yml - Example configuration
@@ -611,7 +611,7 @@ s3:
         max_concurrency: 10
 ```
 
-## Running the Examples
+## Running the Examples {#running-the-examples}
 
 1. **Setup Configuration**
    ```bash

docs/getting_started/installation.md

@@ -2,7 +2,7 @@
 
 The following sections describe how to install the `cgatcore` framework.
 
-## Conda installation
+## Conda installation {#conda-installation}
 
 The preferred method of installation is using Conda. If you do not have Conda installed, you can install it using [Miniconda](https://conda.io/miniconda.html) or [Anaconda](https://www.anaconda.com/download/#macos).
 
@@ -12,21 +12,21 @@ The preferred method of installation is using Conda. If you do not have Conda in
 conda install -c conda-forge -c bioconda cgatcore
 ```
 
-### Prerequisites
+### Prerequisites {#prerequisites}
 
 Before installing `cgatcore`, ensure that you have the following prerequisites:
 
 - **Operating System**: Linux or macOS
 - **Python**: Version 3.6 or higher
 - **Conda**: Recommended for dependency management
 
-### Troubleshooting
+### Troubleshooting {#troubleshooting}
 
 - **Conda Issues**: If you encounter issues with Conda, ensure that the Bioconda and Conda-Forge channels are added and prioritized correctly.
 - **Pip Dependencies**: When using pip, manually install any missing dependencies listed in the error messages.
 - **Script Errors**: If the installation script fails, check the script's output for error messages and ensure all prerequisites are met.
 
-### Verification
+### Verification {#verification}
 
 After installation, verify the installation by running:
 
@@ -41,15 +41,15 @@ print(cgatcore.__version__)
 
 This should display the installed version of `cgatcore`.
 
-## Pip installation
+## Pip installation {#pip-installation}
 
 We recommend installation through Conda because it manages dependencies automatically. However, `cgatcore` is generally lightweight and can also be installed using the `pip` package manager. Note that you may need to manually install other dependencies as needed:
 
 ```bash
 pip install cgatcore
 ```
 
-## Automated installation
+## Automated installation {#automated-installation}
 
 The preferred method to install `cgatcore` is using Conda. However, we have also created a Bash installation script, which uses [Conda](https://conda.io/docs/) under the hood.
 
@@ -78,7 +78,7 @@ conda activate cgat-c
 
 The installation script will place everything under the specified location. The aim of the script is to provide a portable installation that does not interfere with existing software environments. As a result, you will have a dedicated Conda environment that can be activated as needed to work with `cgatcore`.
 
-## Manual installation
+## Manual installation {#manual-installation}
 
 To obtain the latest code, check it out from the public Git repository and activate it:
 
@@ -94,7 +94,7 @@ To update to the latest version, simply pull the latest changes:
 git pull
 ```
 
-## Installing additional software
+## Installing additional software {#installing-additional-software}
 
 When building your own workflows, we recommend using Conda to install software into your environment where possible. This ensures compatibility and ease of installation.
 
@@ -105,7 +105,7 @@ conda search <package>
 conda install <package>
 ```
 
-## Accessing the libdrmaa shared library
+## Accessing the libdrmaa shared library {#accessing-libdrmaa}
 
 You may also need access to the `libdrmaa.so.1.0` C library, which can often be installed as part of the `libdrmaa-dev` package on most Unix systems. Once installed, you may need to specify the location of the DRMAA library if it is not in a default library path. Set the `DRMAA_LIBRARY_PATH` environment variable to point to the library location.