Unlock the Power of CSE Documentation: A Comprehensive Guide

Want to supercharge your experience with CSE? Delve into the world of CSE documentation, and learn how to build, customize, and contribute. This guide will walk you through everything from setting up your environment to mastering advanced table processing techniques, all while optimizing your documentation for maximum impact.

Why Bother Building Documentation?

Understanding your tools leads to mastery. Concise, well-built documentation means:

• Faster learning: Quickly grasp concepts and workflows.
• Improved efficiency: Streamline your development process.
• Reduced errors: Minimize mistakes with clear instructions.

Setup Your Environment: The Essential Tools

Before you dive into building, gather your tools. This section outlines the necessary software and provides setup guidance.

Must-Have Dependencies

• Ruby: Grab a recent version (2.4+) for Rake.
• Pandoc: Version 1.17.2 is critical for markup conversion. Use conda install -c edurand pandoc=1.17.2 for easy setup.
• Git: Version control manager for source code management.
• Microsoft C++ Build Tools: Essential for parsing parameter names from CSE source code using the cl program.

Optional Enhancements

• Node.js: For compression of HTML/CSS, optimize the website.
• LaTeX: Use for PDF output (MiKTeX recommended for Windows). Enable with build-pdf?: true in config.yaml.

Building the Documentation: Step-by-Step

Ready to roll? Here's how to build CSE documentation using Rake, the Ruby build tool.

1. Navigate: Open your terminal and go to the documentation directory.
2. List Commands: Type rake -T to see available commands.
3. Execute Build: Run rake build or simply rake to initiate the default build process.

Configuration is Key: Customize Your Build

The config.yaml file lets you tailor the build process to your needs. Override the defaults in doc/config/defaults.yaml by creating a local doc/config.yaml. Customize settings like:

• use-node?: true for Node.js-based compression.
• build-pdf?: true to enable PDF generation.
• context: allows you to define variables to pass and pre-process using embedded Ruby

Unleash Embedded Ruby (ERB): Dynamic Content Generation

ERB enables dynamic content generation within your Markdown files.

• Conditional Inclusion: Adapt content based on defined variables.
• Context Variables: Define variables in config.yaml to control ERB behavior– remember that they must start with a lowercase letter or an underscore.

Testing ERB: Ensure Correct Processing

Use the rake erb task for testing:

rake erb FILE=path/to/your/file.md

This command preprocesses your file and outputs the result to doc/erb-out.txt.

Streamlining Content with insert_file

Avoid repetition by inserting file content directly into Markdown documents. Use the following directive:

<%= insert_file('path/to/your/file.md') %>

This will insert the content from the specified file, relative to the repository root.

Mastering Table Pre-processing: CSV Tables and More

The build process has robust table pre-processing capabilities that can be configured by setting use-table-lang?: true.

Table Directives

• member_table: Creates formatted tables for record member descriptions. Supply data as a Ruby hash.
• csv_table: Embed CSV data directly within Markdown files. Use quotes for special characters like commas.
• csv_table_from_file: Load CSV data from external files. Edit tables easily using spreadsheet software.

csv_table_from_file Example

<%= csv_table_from_file("input-data--member-table-definition.csv") %>

Support Files: The Backbone of Documentation

The doc/config/ directory contains essential support files:

• defaults.yaml: Default configuration parameters.
• css/: CSS for HTML styling.
• template/: Templates for HTML and LaTeX.
• reference/: Includes probes.txt (CSE output), probes_input.yaml (processed data).

Record Index Exceptions: Handling Deviations

The record-index-exceptions.yaml file is used for locating a Record's "canonical location" in the documentation source. Use it in circumstances that the source of your record doesn't follow typical conventions (file named after the record in lowercase).

Get Involved

Building documentation is a collaborative effort. By following this guide, you're not just documenting; you're contributing to a more accessible and understandable CSE ecosystem.