(WIP) docs: Fix for some of the documentation formatting issues (#381)

* Add blank lines for improved readability in format.md

* Fix: (docs) blanks-around-lists and blanks-around-headings errors in format.md

* Fix: (docs) add missing newlines at the end of file, and added blanked spaces after headings and fences for improved formatting in built-in-reference.md and overview.md

* Reverting the description of GRPO formatter

* Update docs/formatters/built-in-reference.md

Added comments describing ```standardize_data_formats``` and ```formatting_prompts_func```.

Co-authored-by: gemini-code-assist[bot] <176961590+gemini-code-assist[bot]@users.noreply.github.com>

* Fix: (docs) add missing newlines at the end of files and ensure consistent formatting in multiple documentation files for improved readability

---------

Co-authored-by: Jyotirmay Chakraborty <93432859+UltimatePlutoC@users.noreply.github.com>
Co-authored-by: gemini-code-assist[bot] <176961590+gemini-code-assist[bot]@users.noreply.github.com>

Author: jyotirmayc

docs/cli/format.md

@@ -75,6 +75,7 @@ dataset:
 Formats data for Alpaca-style instruction tuning.
 
 **Default configuration:**
+
 ```yaml
 instruction_template: "### Instruction:\n{instruction}\n\n### Response:"
 include_empty_input: false
@@ -85,6 +86,7 @@ include_empty_input: false
 Formats data in ChatML format (structured or text).
 
 **Default configuration:**
+
 ```yaml
 output_format: "text"
 start_token: "<|im_start|>"
@@ -97,6 +99,7 @@ include_system: false
 Formats data for GRPO (Guided Reasoning Process Optimization) training.
 
 **Default configuration:**
+
 ```yaml
 reasoning_start_tag: "<start_working_out>"
 reasoning_end_tag: "<end_working_out>"
@@ -109,6 +112,7 @@ solution_end_tag: "</SOLUTION>"
 The command expects a JSONL file where each line is a JSON object. Supported formats include:
 
 1. **Question-Answer format:**
+
 ```json
 {
   "question": "What is recursion?",
@@ -117,6 +121,7 @@ The command expects a JSONL file where each line is a JSON object. Supported for
 ```
 
 2. **Messages format:**
+
 ```json
 {
   "messages": [
@@ -127,6 +132,7 @@ The command expects a JSONL file where each line is a JSON object. Supported for
 ```
 
 3. **Instruction format:**
+
 ```json
 {
   "instruction": "Write a function to calculate factorial",
@@ -140,6 +146,7 @@ The command expects a JSONL file where each line is a JSON object. Supported for
 You can now format datasets directly from the Hugging Face Hub using `--repo`, or continue using local JSONL files. Many HF datasets come in compatible formats:
 
 **Format directly from a Hub repo:**
+
 ```bash
 # Pull from Hub, format to Harmony, write to formatted.jsonl
 deepfabric format --repo "org/dataset-name" --format harmony
@@ -153,6 +160,7 @@ PY
 ```
 
 **For datasets with `messages` field (e.g., chat datasets):**
+
 ```bash
 # Download dataset using datasets library or git
 huggingface-cli download microsoft/DialoGPT-medium --repo-type dataset
@@ -169,18 +177,21 @@ deepfabric format orca_math.jsonl -f chatml
 ```
 
 **For datasets with instruction format (e.g., Alpaca-style):**
+
 ```bash
 # Many HF datasets use instruction/input/output format
 deepfabric format alpaca_dataset.jsonl -f chatml
 ```
 
 **Common HuggingFace dataset formats supported:**
+
 - OpenAI ChatML format (`messages` field)
 - Alpaca format (`instruction`, `input`, `output`)
 - ShareGPT format (`conversations`)
 - Q&A format (`question`, `answer` or `response`)
 
 **Example conversion workflow (local):**
+
 ```bash
 # 1. Download from HuggingFace
 huggingface-cli download tatsu-lab/alpaca --repo-type dataset
@@ -196,11 +207,13 @@ deepfabric format alpaca.jsonl -f grpo -o alpaca_grpo.jsonl
 ## Workflow Example
 
 1. Generate a dataset:
+
 ```bash
 deepfabric generate config.yaml
 ```
 
 2. Apply different formatters to the same dataset:
+
 ```bash
 # For ChatML training
 deepfabric format dataset_raw.jsonl -f chatml -o dataset_chatml.jsonl
@@ -213,6 +226,7 @@ deepfabric format dataset_raw.jsonl -f grpo -o dataset_grpo.jsonl
 ```
 
 This allows you to prepare the same dataset for different training frameworks without regenerating the data.
+
 ### TRL SFT Tools
 
 Use `-f trl` to convert agent/tool datasets to the Hugging Face TRL SFT tool-calling format. This maps to the built-in `trl_sft_tools` formatter.

docs/cli/generate.md

@@ -162,4 +162,4 @@ python -m json.tool your_dataset.jsonl > /dev/null
 wc -l your_dataset.jsonl
 ```
 
-This validation ensures the generation process completed successfully and produced properly formatted output ready for use in training or evaluation pipelines.
+This validation ensures the generation process completed successfully and produced properly formatted output ready for use in training or evaluation pipelines.

docs/cli/index.md

@@ -86,4 +86,4 @@ Detailed documentation for each command covers syntax, options, examples, and co
 [**visualize**](visualize.md) - Topic graph visualization and analysis
 [**upload**](upload.md) - Hugging Face Hub integration and publishing
 
-Each command section includes practical examples, common usage patterns, and troubleshooting guidance for typical issues encountered during synthetic data generation workflows.
+Each command section includes practical examples, common usage patterns, and troubleshooting guidance for typical issues encountered during synthetic data generation workflows.

docs/cli/upload.md

@@ -150,4 +150,4 @@ Subsequent uploads to existing repositories update both data and metadata:
 **Change Documentation** automatically updates dataset cards to reflect changes in generation methodology or content characteristics.
 
 ??? tip "Publication Best Practices"
-    Review generated dataset cards before publication and consider adding domain-specific usage notes or limitations. Use descriptive repository names and comprehensive tagging to maximize appropriate discovery and usage of your synthetic datasets.
+    Review generated dataset cards before publication and consider adding domain-specific usage notes or limitations. Use descriptive repository names and comprehensive tagging to maximize appropriate discovery and usage of your synthetic datasets.

docs/cli/validate.md

@@ -30,7 +30,7 @@ The validation process examines multiple aspects of your configuration:
 
 Successful validation produces a summary of your configuration:
 
-```
+```bash
  Configuration is valid
 
 Configuration Summary:
@@ -49,7 +49,7 @@ The summary provides an overview of key parameters, while warnings highlight pot
 
 Configuration problems are reported with clear categorization and guidance:
 
-```
+```bash
 ❌ Configuration validation failed:
   - data_engine section is required
   - Invalid provider 'invalid_provider' in topic_tree
@@ -66,7 +66,7 @@ Beyond basic validation, the command provides insights into your configuration c
 deepfabric validate config.yaml
 ```
 
-```
+```bash
 Configuration Analysis:
   Estimated generation time: 15-25 minutes
   Estimated API costs: $2.50-4.00 (OpenAI GPT-4)
@@ -87,7 +87,7 @@ For OpenAI configurations, it verifies model name formats and availability. For
 deepfabric validate config.yaml
 ```
 
-```
+```bash
 Provider Validation:
    OpenAI API key detected (OPENAI_API_KEY)
    Model gpt-4 is available
@@ -141,4 +141,4 @@ The validate command uses standard exit codes for scripting integration:
 These exit codes enable reliable automation and continuous integration workflows where configuration validation is part of the build process.
 
 ??? tip "Continuous Validation Strategy"
-    Consider adding configuration validation to your version control hooks or continuous integration pipeline. This practice catches configuration regressions and ensures that all committed configurations are functional and ready for use.
+    Consider adding configuration validation to your version control hooks or continuous integration pipeline. This practice catches configuration regressions and ensures that all committed configurations are functional and ready for use.

docs/cli/visualize.md

@@ -112,4 +112,4 @@ Generated SVG files are self-contained vector graphics that:
 - Use standard web colors and fonts for maximum compatibility
 
 ??? tip "Visualization Best Practices"
-    Generate visualizations after topic graph creation but before dataset generation to validate topic coverage and relationships. Use visualizations to identify overly dense or sparse areas in your domain coverage, then adjust generation parameters accordingly.
+    Generate visualizations after topic graph creation but before dataset generation to validate topic coverage and relationships. Use visualizations to identify overly dense or sparse areas in your domain coverage, then adjust generation parameters accordingly.

docs/formatters/built-in-reference.md

@@ -59,20 +59,23 @@ formatters:
 ### Framework Compatibility
 
 **Unsloth:**
+
 ```python
 dataset = load_dataset("your-username/your-dataset", split="train")
-dataset = standardize_data_formats(dataset)
-dataset = dataset.map(formatting_prompts_func, batched=True)
+dataset = standardize_data_formats(dataset) # Placeholder for data standardization
+dataset = dataset.map(formatting_prompts_func, batched=True) # Placeholder for formatting function
 ```
 
 **Axolotl:**
+
 ```yaml
 datasets:
   - path: your-username/your-dataset
     type: conversation
 ```
 
 **HuggingFace TRL:**
+
 ```python
 from trl import SFTTrainer
 trainer = SFTTrainer(
@@ -231,6 +234,7 @@ config:
 ### Role Hierarchy
 
 The Harmony format enforces a strict role hierarchy (highest to lowest priority):
+
 1. **system** - System instructions and metadata
 2. **developer** - Developer instructions and tool definitions
 3. **user** - User messages
@@ -240,6 +244,7 @@ The Harmony format enforces a strict role hierarchy (highest to lowest priority)
 ### Channels
 
 Assistant messages can be assigned to different channels:
+
 - **final**: User-facing responses (default)
 - **analysis**: Internal chain-of-thought reasoning (not safe for user display)
 - **commentary**: Function tool calls and preambles
@@ -254,6 +259,7 @@ Assistant messages can be assigned to different channels:
 ### Output Formats
 
 **Text Format** (`output_format: "text"`):
+
 ```text
 <|start|>system<|message|>
 You are ChatGPT, a large language model trained by OpenAI.
@@ -289,6 +295,7 @@ The weather in London is currently 18°C with cloudy conditions.
 ```
 
 **Structured Format** (`output_format: "structured"`):
+
 ```json
 {
   "messages": [
@@ -360,6 +367,7 @@ namespace functions {
 ### Example Configurations
 
 **Basic Chat Configuration**:
+
 ```yaml
 formatters:
 - name: "harmony_chat"
@@ -372,6 +380,7 @@ formatters:
 ```
 
 **Advanced Configuration with Tools**:
+
 ```yaml
 formatters:
 - name: "harmony_tools"
@@ -390,6 +399,7 @@ formatters:
 ```
 
 **Chain-of-Thought Configuration**:
+
 ```yaml
 formatters:
 - name: "harmony_cot"
@@ -503,20 +513,23 @@ formatters:
 ### Advanced Configuration
 
 **Disable Reasoning Prefixes**:
+
 ```yaml
 config:
   include_reasoning_prefix: false
   tool_call_format: "<tool_call>\n{tool_call}\n</tool_call>"
 ```
 
 **Custom Tool Call Format**:
+
 ```yaml
 config:
   tool_call_format: "FUNCTION_CALL: {tool_call}"
   reasoning_prefix_template: "Let me {action}."
 ```
 
 **Plain Text Tool Responses**:
+
 ```yaml
 config:
   tool_response_as_json: false
@@ -629,6 +642,7 @@ formatters:
 ### Advanced Configuration
 
 **Override System Prompt for Training**:
+
 ```yaml
 config:
   include_system_prompt: true
@@ -639,12 +653,14 @@ config:
 ```
 
 **Clean Output (Remove Original Tools Field)**:
+
 ```yaml
 config:
   remove_available_tools_field: true
 ```
 
 **Disable Schema Validation (Performance)**:
+
 ```yaml
 config:
   validate_tool_schemas: false
@@ -666,6 +682,7 @@ deepfabric format --repo org/agent-dataset --formatter trl -o trl_formatted.json
 ```
 
 This workflow is ideal for:
+
 - Converting existing agent/tool datasets to TRL format
 - Reformatting community datasets for your training pipeline
 - Experimenting with different formatters on public datasets
@@ -753,6 +770,7 @@ config:
 ### Output Formats
 
 **Structured Format** (`output_format: "structured"`):
+
 ```json
 {
   "messages": [
@@ -764,6 +782,7 @@ config:
 ```
 
 **Text Format** (`output_format: "text"`):
+
 ```json
 {
   "text": "<|im_start|>system\nYou are a helpful assistant.\n<|im_end|>\n<|im_start|>user\nHello!\n<|im_end|>\n<|im_start|>assistant\nHi there! How can I help you today?\n<|im_end|>"
@@ -788,31 +807,36 @@ formatters:
 ## Choosing the Right Formatter
 
 ### For Mathematical Reasoning Training
+
 - **GRPO**: When training models to show step-by-step reasoning with extractable answers
 - **Harmony**: For models that need to show internal reasoning (analysis channel) separate from final answers
 - **Alpaca**: For instruction-following with math problems
 - **ChatML**: For conversational math tutoring scenarios
 
 ### For General Instruction Following
+
 - **Alpaca**: Standard instruction-following format
 - **ChatML**: When you need conversation context and role clarity
 - **Harmony**: For gpt-oss models with developer instructions and role hierarchy
 - **Conversations**: For Unsloth, Axolotl, or HF TRL training with conversations format
 
 ### For Chat and Dialogue
+
 - **Harmony**: Advanced format with channels, tool support, and role hierarchy for gpt-oss models
 - **ChatML**: ChatML-compatible format with `<|im_start|>/<|im_end|>` delimiters
 - **Conversations**: Standard conversations format for multiple frameworks
 - **Alpaca**: Single-turn instruction-response pairs
 
 ### For Tool/Function Calling
+
 - **TRL SFT Tools**: HuggingFace TRL SFTTrainer with OpenAI function schema (recommended for modern training workflows)
 - **Single Tool Call**: Individual tool call format with each call in its own message exchange
 - **Tool Calling**: Embedded tool calling with thinking traces and multiple tools per response
 - **Harmony**: TypeScript-style function definitions with channels for tool calls and responses
 - **Custom formatters**: For specific tool calling conventions
 
 ### For Custom Requirements
+
 Create a [custom formatter](custom-formatter-guide.md) that inherits from BaseFormatter.
 
 ## Validation and Error Handling
@@ -829,4 +853,4 @@ All built-in formatters include:
 - Built-in formatters are optimized for both speed and memory efficiency
 - Large datasets are processed in streaming fashion when possible
 - Validation can be disabled for better performance in production
-- Formatter instances are cached for repeated use
+- Formatter instances are cached for repeated use

docs/formatters/overview.md

@@ -113,4 +113,4 @@ The formatter system includes comprehensive error handling:
 
 - [Built-in Formatter Reference](built-in-reference.md) - Documentation for all included formatters
 - [Custom Formatter Guide](custom-formatter-guide.md) - How to create your own formatters
-- [API Reference](api-reference.md) - Complete API documentation
+- [API Reference](api-reference.md) - Complete API documentation