[[Include(WikiToC)]] [[TOC(noheading)]] == Contributing to the Wiki For consistent wiki formatting, please adhere to the following style guidelines. [[PageOutline(3-6,,inline,unnumbered)]] === General Guidelines * '''Page Naming''' * Use a short and descriptive name using CamelCase (e.g. `MyPageName`) * '''Headings''' * Start page titles at depth corresponding to the page depth: * /wiki/PageName uses `= My Page Title` * /wiki/SectionName/PageName uses `== My Page Title` * The number of `=` equals the depth (e.g. `===` is depth 3) * '''Links''' * '''DO NOT''' use full URLs (i.e. !http://wiki.cosmos-lab.org/...) when linking to pages within the wiki. Use the [wiki:WikiFormatting#Links WikiPageNames link syntax] instead. * When linking to pages that are children of the current page, use relative paths `[wiki:./page/to/link/to text to display]` instead of the absolute wiki path. * '''Instructions containing shell commands''' * For commands that will be copy pasted, ensure no prompt is present. * For bash scripts, start the code block with {{{ {{{#!shell }}} * For terminal sessions, start the code block with {{{ {{{#!shell-session }}} * If the command is to be run on a console: make sure the prompt starts with {{{user@console:path$}}} * If the command is to be run on a compute machine: make sure the prompt starts with {{{root@node-name:path$}}} === Page Specific Formatting ==== Section Pages Pages that are introductory to larger sections that contain many sub-pages (e.g. the [wiki:tutorials Tutorials] page) should use the following as a starting point: {{{ [[Include(WikiToC)]] = Section Title Brief description of the section... [[TOC(SectionPageName/*,inline,nonumbering,notitle,noheading,depth=2)]] }}} The TOC macro will auto-generate an alphabetical inline list of links to sub-pages of the section. If the sub-pages need to have a specific order, feel free to edit the TOC macro or create the list by hand, but try to keep the style as similar as possible. ==== Individual Pages Individual wiki pages should use the following as a starting point: {{{ [[Include(WikiToC)]] == Page Title Brief description of the page... [[PageOutline(3-6,,inline,unnumbered)]] === Sub Section Title Sub section content... }}} {{{#!box type=note For pages nested deeper, please increase the number of equal signs in the headings to account for the page depth accordingly (though max heading depth is 6). Otherwise, the auto-generated table of contents on parent pages may not generate correctly. }}} ==== Tutorial Pages Please us the following document skeleton when writing a tutorial. {{{ {{{ [[Include(WikiToC)]] == Tutorial Title === Description Description and goal of the tutorial described here... [[PageOutline(3-6,,inline,unnumbered)]] === Prerequisites In order to access the test bed, create a reservation and have it approved by the reservation service. Access to the resources is granted after the reservation is confirmed. Please follow the process shown on [wiki:cosmos_workflow the COSMOS work flow page] to get started. === Resource Requirements List of specific resources or requirements, including OMF image name if applicable. === Setup Steps to setup the tutorial... === Execution ==== The first thing you do First step of the tutorial... ==== The second thing you do Second step of the tutorial... }}} }}} === Code Blocks and Syntax Highlighting When including raw source code blocks, try to use the appropriate syntax highlighting for the language used. Trac uses [https://pygments.org/docs/lexers/ pygments] to do syntax highlighting in code blocks. ==== Example 1 {{{ {{{#!shell echo "foo" }}} }}} will be rendered as {{{#!shell echo "foo" }}} ==== Example 2 {{{ {{{#!ruby defTopology('rxnode') { |t| # Load the topology of imaged nodes # These nodes are from most recent omf load command baseTopo = Topology['system:topo:imaged'] # Draw a random node from the pool of active ones aNode = baseTopo.getUniqueRandomNode # Add this random node to this 'senderTopo' topology t.addNode(aNode) puts "RX: #{t.getNodeByIndex(0).to_s}" } }}} }}} will be rendered as {{{#!ruby defTopology('rxnode') { |t| # Load the topology of imaged nodes # These nodes are from most recent omf load command baseTopo = Topology['system:topo:imaged'] # Draw a random node from the pool of active ones aNode = baseTopo.getUniqueRandomNode # Add this random node to this 'senderTopo' topology t.addNode(aNode) puts "RX: #{t.getNodeByIndex(0).to_s}" } }}} ==== Common formats ||=Language =||=Shortname for Codeblock =|| || shell script || bash, sh, ksh, zsh, shell || || shell session || console, shell-session || || powershell || powershell, posh, ps1, psm1 || || ruby session || rbcon, irb || || ruby code || rb, ruby, duby || || json || json || || json w no braces || json-object || || yaml, yml || yaml || || mix of yaml and jinja ||yaml+jinja, salt, sls || || docker || docker, dockerfile || === Using Markdown or !RestructuredText To use Markdown instead of Tracs' own language, simply enclose the Markdown text in a code block starting with `#!Markdown` like this: {{{ {{{#!Markdown # Some Title Sample text. ## A Sub Section More sample text. ### Yet another sub section Even more sample text. }}} }}} or if you want to use !RestructuredText instead, start the code block with `#!rst` like this: {{{ {{{#!rst ********** Some Title ********** Sample text. A Sub Section ############# More sample text. Yet another sub section *********************** Even more sample text. }}} }}}