Unlock the Power of CSE Documentation: A Developer's Guide to Building and Customizing

Are you ready to dive deep into customizing and building documentation for the CSE (Complex Systems Engineering) framework? This comprehensive guide will walk you through every step, transforming you from a documentation novice to a proficient builder. We'll explore the essential tools, configurations, and techniques needed to create stellar CSE user manuals.

Why Bother Customizing Your CSE Documentation?

• Tailored Information: Create user manuals reflecting your specific CSE implementation and workflows.
• Enhanced Clarity: Improve comprehension with customized examples and explanations.
• Streamlined Development: Integrate documentation seamlessly into your CSE development lifecycle.

Essential Tools for CSE Documentation Mastery

Before you start, ensure you have these tools installed and ready to go. These tools will allow you to convert markup languages, handle dependencies, and much more.

• Pandoc: Convert Markdown to various formats. Important: Version 1.17.2 is crucial for compatibility!
• Ruby: A dynamic programming language. Use any version NOT at end-of-life (currently Ruby 2.4+)
• (Optional) Node.js: Compress HTML/CSS for efficient website performance.
• (Optional) LaTeX System: Generate PDF outputs from your documentation.
• Git: Version control for tracking changes and collaboration.

Setting Up Pandoc 1.17.2: The Cornerstone of CSE Documentation

Got a newer version of Pandoc already installed? No problem! Use conda, a package, dependency, and environment manager, to isolate Pandoc 1.17.2. Here's how:

1. Install Miniconda: Download and install miniconda from the official website.
2. Create a Conda Environment: Open your terminal and run: conda create --name cse-docs.
3. Activate the Environment:
   • Windows: activate cse-docs
   • macOS/Linux: source activate cse-docs
4. Install Pandoc 1.17.2: conda install -c edurand pandoc=1.17.2
5. Activate Pandoc: Remember to run source activate cse-docs each time you want to use this specific Pandoc version.

Streamlining Your Workflow with Rake: Ruby's Build Automation Tool

Rake simplifies the build process. It's like "make" but for Ruby and it comes included with most Ruby installations. Use rake -T in the documentation directory to view all available commands.

• Build: Execute the default build command: rake build or simply rake.

Configuring Your CSE Documentation: config.yaml is Your Friend

Customize your builds! Override default settings by creating a doc/config.yaml file. This file lets you define specific parameters for your documentation generation, like enabling Node.js compression or building PDF outputs. Here's an example:

use-node?: true
build-pdf?: true
context:
  build_all: true

Unleashing the Power of Embedded Ruby (ERB) for Dynamic Documentation

ERB brings your documentation to life! Embed Ruby code directly within your Markdown files for conditional content, calculations, and more. This allows you to tailor the manual based on specific build contexts.

• Conditional Content: Use <% if dev_build %> to include or exclude sections based on defined variables. Remember to keep your variable names lowercase!

Testing Your ERB Code: Ensuring Accuracy and Reliability

Before committing your changes, test your ERB code using the rake erb task. This ensures the code renders correctly within your documentation generation process.

• Run the Task: rake erb FILE=path/to/your/file.md (Unix/macOS) or set FILE=path\to\file.md & rake erb (Windows).

Inserting External Content: Keeping Your Documentation DRY (Don't Repeat Yourself)

Avoid redundancy! The insert_file directive lets you seamlessly include external files into your Markdown documents. This ensures consistency and simplifies updates.

• Usage: <%= insert_file('doc/src/your_file.md') %> Paths are relative to the repository root.

Taming Tables with Pre-processing Directives

Want better-looking tables directly from imported data? Utilize ERB with use-table-lang?: true to enable the use of several table pre-processing directives. These directives allow you to transform imported CSV data, in-file CSV data, or special tables easily.

Leverage member_table for record member tables

The member_table directive allows you to write Markdown tables that include units, legal ranges, variability, etc. The arguments to member_table are Ruby hashes or dictionaries.

<%= member_table(
units: "1/^o^F",
legal_range: "no restrictions",
default: "-0.0026",
required: "No",
variability: "constant") %>

Easily Convert CSV data to tables using csv_table

Use csv_table with inline CSV data to add tables to your documents through the use of the <<END operator. You can define whether there will be a row header or not through the use of :row_header => true for example.

<%= csv_table(<<END,:row_header => true)
"Property","Value"
"*Units*","units of measure (lb., ft, Btu, etc.) where applicable"
"*Legal*","limits of valid range for numeric inputs; valid ""choices"""
END
%>

Use external CSV files as tables with csv_table_from_file

This directive loads a CSV file from the file system, this works best when you are editing the data in a spreadsheet tool that can save as CSV.

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

Diving Deeper: Understanding Support Files

doc/config/ houses crucial support files. defaults.yaml defines default configurations. The css directory stores HTML styling, while the template directory contains HTML and LaTeX templates.

Level Up Your Documentation Game

By mastering these techniques, you can transform the CSE documentation from a chore to a powerful asset and make it an integral part of the development process.