[[Include(WikiToC)]]
[[TOC(noheading)]]

== Contributing to the Wiki

For consistent wiki formatting, please adhere to the following style guidelines.

=== General Guidelines
* '''Page Naming'''
  * Use a short and descriptive name using CamelCase (eg. `MyPageName`)
* '''Headings'''
  * Start page titles at depth 1 (ie. `= My Page Title`)
  * The number of `=` equals the depth (eg. `===` is depth 3)
* '''Links'''
  * '''DO NOT''' use full URLs (ie. !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 links `[wiki:./page/to/link/to text to display]`

=== Page Specific Formatting

==== Section Pages
Pages that are introductory to larger sections that contain many sub pages (eg. the main [wiki:TestbedInformation Testbed Information] page or the [wiki:tutorials Tutorials] page) should use the following as a starting point:

{{{
[[TOC(SectionPageName/SubsectionPageName/*, depth=1, noheading)]]

= Section Title
Brief description of the section.

To list pages below this one, use:
[[TOC(./*,nonumbering,depth=2)]]
}}}

'''NOTE:''' Please remember to put the wiki URL corresponding to the page name in the TOC macro. You can see the wiki URL at the top of the page during editing.

  ''Example:'' For this page, the top of the page says "''Editing test/ExperimenterInformation/WikiStyleGuide''", so the TOC macro should then be `[[TOC(test/ExperimenterInformation/WikiStyleGuide/*,depth=1)]]`. Don't forget to add the `/*` at the end of the wiki URL.

The default TOC depth should be left at 1, unless it makes sense otherwise.

==== Individual Pages
Individual wiki pages should use the following as a starting point:
{{{
[[Include(WikiToC)]]
[[TOC(noheading)]]

= Page Title
Brief description of the page.

== Sub Section Title
Sub section content.
}}}

==== Tutorial Pages

Please us the following document skeleton when writing a tutorial.

{{{
{{{
[[TOC(noheading)]]

= Tutorial Title

== Description
Description and goal of the tutorial described here...

== 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...
}}}
}}}


=== Syntax Highlighting and code blocks

Trac uses [https://pygments.org/docs/lexers/ pygments] to do syntax highlighting in code blocks
{{{
{{{#!shell
  echo "foo"
}}}

or

{{{#!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

Using code blocks like before, Trac can render other markup formats
{{{
{{{#!Markdown
# heading 1
## heading 2
### heading 3
}}}
}}}