class
Crycco::Section
- Crycco::Section
- Reference
- Object
Overview
Section
Document contents are organized in sections, which have docs and code. The docs are markdown extracted from comments and the code is the actual code.
Sections can be converted to HTML using the #docs_html and #code_html methods.
Defined in:
crycco.crConstructors
-
.new(language : Language, path : Path)
On initialization we get the language definition and create a lexer and formatter for code highlighting.
Instance Method Summary
-
#anchor : String
Extract the first header from documentation for semantic anchoring
- #code : String
- #code=(code : String)
-
#code_html
All the code is passed through the formatter to get syntax highlighting
- #docs : String
- #docs=(docs : String)
-
#docs_html
Converting Documentation to HTML
-
#file_exists?(file_path : Path) : Bool
Check if a file exists in the processed files list
- #html_path_for_file(file_path : Path) : String
- #language : Language
- #language=(language : Language)
- #path : Path
- #path=(path : Path)
- #process_file_references(text : String) : String
- #resolve_file_reference(ref_name : String) : String | Nil
- #resolve_symbol_reference(symbol_name : String) : String | Nil
-
#to_h : Hash(String, String)
The
#to_hmethod is used to turn the section into something that can be handled by the Crinja template engine. -
#to_literate : String
#to_literateconverts the section into valid markdown with code blocks as indented blocks. -
#to_markdown : String
#to_markdownconverts the section into valid markdown with code blocks for the source code. -
#to_source : String
#to_sourceregenerates valid source code out of the section.
Constructor Detail
On initialization we get the language definition and create a lexer and formatter for code highlighting.
Instance Method Detail
Converting Documentation to HTML
The #docs_html method is responsible for converting the documentation
portion of each section into final HTML output. This is where the
smart file reference processing happens.
The process is:
- Process any smart file and symbol references (convert
[[file]]and[[Symbol]]to proper links) - Convert the resulting Markdown to HTML using Markd
This means that writers can use both Markdown syntax AND smart file/symbol references in their documentation comments, and they'll both be handled correctly in the final output.
You can see the implementation details of the Markdown processing
in [[markd.cr]] and the smart reference processing in the #process_file_references
method above.
The #to_h method is used to turn the section into something that can be
handled by the Crinja template engine. Just takes the data and put it in
a hash.
#to_literate converts the section into valid markdown with code blocks
as indented blocks.
#to_markdown converts the section into valid markdown with code blocks
for the source code.
#to_source regenerates valid source code out of the section. This way if
the section was generated by a literate document, we can extract the code
and comments from it and save it to a file.