1.3.3.4. Code or Literal Directives

Note

Your whitespace placement is key in RestructuredText. Take note of the examples of ensuring after a * or #. the next character starts on the next tab line. So 3 or 2 spaces respectively. This will make your code-block render inline with text of list.

Important

You must have only (1) space between .. and code-block:: or another other role called in this manner. Do not tab between.

  • This is a role to document a python code object:

    • Syntax:

      .. py:function:: enumerate(sequence[, start=0])

    Return an iterator that yields tuples of an index and an item of the  *sequence*. (And so on.)

    • Rendered:

      enumerate(sequence[, start=0])

      Returns an iterator that yields tuples of an index and an item of the sequence. (And so on.)

  • This is a role used to display a boxed code-block section for code with an optional caption and optional line numbers.

    Note

    Since Cisco IOS/ASA/IOS-XE does not support a line continuation character, the latex generator will insert space and next line character into PDF. You will have to bring the code block to indent with main document level to have a copy/paste ready code block. Usually happens with ASA firewall rules.

    Or if in landscape and its still too long, you will need to have regular command lines for copy paste and use .. raw:: latex then /begin{scriptsize} and /end{scriptsize}

    Note

    You can include variables from your yaml or contexts by using {{ variable }} in the code block and the value will be rendered. You must have at beginning of rst file .. jinja:: and contents tabbed under.

    • Syntax:

      • .. code-block:: {lexer} Use Lexers for RST

      • :linenos: Add Line numbers

      • :lineno-start: {integer} Integer of where to start

      • :caption: {string} Display name

      • :name: {string} Name for ref

      • :emphasize-lines: {integer}

      .. code-block:: python
    :linenos:
    :caption: Code Block
    :name: code_block
    :emphasize-lines: 1

    code line 1 *variable*
    code line 2 **cannot bold**
    You can also include variables like {{ release }}

    • Rendered:

      Code 1.1 Code Block
      1code line 1 *variable*
2code line 2 **cannot bold**
3You can also include variables like

  • This is used to where a large code blocks or literal are needed with markup inside.

    Note

    When rendered in PDF, it does not have a box around it.

    Note

    If you need to do inline markup with italics right after a bold. For example a unknown file name in a command. You will need to use escape character \ then a space between them.

    Note

    You can include variables from your yaml or contexts by using {{ variable }} in the parsed-literal block and the value will be rendered. You must have at beginnging of rst file .. jinja:: and the contents tabbed under.

    • Syntax:

      • :name: {string} Name for ref

      .. parsed-literal::
    :name: parsed_literal

    code line 1 *variable*
    code line 2 **can bold**
    You can also include variables like {{ release }}

    • Rendered:

      code line 1 variable
code line 2 can bold
You can also include variables like {{ release }}

  • This is how you include a plain-text based file to render.

    Note

    There is a .. include:: filename role but with the features of the literalinclude role there isn’t much benefit for it.

    • Syntax:

      • :caption: text - Text caption

      • :name: text - Text name to use for :ref:

      • :dedent: 4 - Removes leading indentation characters from file

      • :language: {lexer} - Use Lexers for RST

      • :emphasize-lines: 1,3-6 Emphasis’s called out lines

      • :linenos: - Turns on Line Numbers

      • :encoding: utf-8-sig - Encoding of file. default: utf-8-sig

      • :pyobject: class.function - Only include the object/class from file if a py file.

      • :lines: 1-10 - Limits rendered output to listed line numbers

      • :diff: filename2 - diffs with listed filename compared to included filename

      .. literalinclude:: /scripts/examples/install.ps1
    :caption: install.ps1
    :name: install.ps1
    :language: none
    :emphasize-lines: 1-2
    :linenos:

    • Rendered:

      Code 1.2 install.ps1
       1param(
 2[parameter(Mandatory=$false)][string]$user = $env:UserName.ToLower(),
 3[parameter(Mandatory=$true)][string]$email = "username@domain.com"
 4)
 5
 6Start-Transcript -path C:\TEMP\install-wsl.log -append
 7
 8# Set distro name
 9$wslDistro = (Get-ChildItem -Path .\Alpine*.exe).Name
10$distroName = $wslDistro.Split('.')[0]
11$wslPath = "C:\Users\$user\.wsl\$distroName"
12$TargetFile = "$wslPath\$wslDistro"
13$ShortcutFile = "C:\Users\$user\Desktop\$distroName WSL.lnk"
14
15# Uninstall previous WSL distro if present
16If (Test-Path $wslPath) {
17    Write-Host -ForegroundColor Yellow ("`nUninstalling previous Windows Subsystem for Linux (WSL), $distroName Linux")
18    Start-Process $wslPath\$wslDistro -ArgumentList "clean" -NoNewWindow -Wait
19    Get-ChildItem -Path $wslPath -Recurse | Remove-Item -force -recurse
20    Remove-Item -Force $wslPath
21    Remove-Item -Force $ShortcutFile
22    Write-Host -ForegroundColor Yellow ("`nPrevious Windows Subsystem for Linux (WSL), $distroName Linux FOUND and REMOVED.")
23}
24Else {
25    Write-Host -ForegroundColor Yellow ("`nPrevious Windows Subsystem for Linux (WSL), $distroName Linux NOT found.")
26}
27
28# Install WSL Distro
29Write-Host -ForegroundColor Yellow ("`nInstalling Windows Subsystem for Linux (WSL), $distroName Linux to $wslPath")
30Invoke-Command -ScriptBlock { Copy-Item -Recurse -Path .\ -Destination $args[0] -Force } -ArgumentList $wslPath
31
32Start-Process $wslPath\$wslDistro -ArgumentList "install" -NoNewWindow -Wait
33Start-Process $wslPath\$wslDistro -ArgumentList "run cd /usr/share/texmf-dist/tex/latex/acrotex; sudo latex acrotex.ins" -NoNewWindow -Wait # would like to add this to makefile
34Start-Process $wslPath\$wslDistro -ArgumentList "run sudo mktexlsr" -NoNewWindow -Wait # would like to add this to makefile
35Start-Process $wslPath\$wslDistro -ArgumentList "run sudo git config --system core.autocrlf false"  -NoNewWindow -Wait
36Start-Process $wslPath\$wslDistro -ArgumentList "run sudo git config --system core.symlinks false"  -NoNewWindow -Wait
37Start-Process $wslPath\$wslDistro -ArgumentList "run sudo git config --system rebase.autosquash true" -NoNewWindow -Wait
38Start-Process $wslPath\$wslDistro -ArgumentList "run sudo git config --system lfs.activitytimeout 0" -NoNewWindow -Wait
39Start-Process $wslPath\$wslDistro -ArgumentList "run sudo git config --system credential.helper 'cache --timeout 30000'" -NoNewWindow -Wait
40Start-Process $wslPath\$wslDistro -ArgumentList "run sudo git config --system color.diff false" -NoNewWindow -Wait
41Start-Process $wslPath\$wslDistro -ArgumentList "run git lfs install"  -NoNewWindow -Wait
42Write-Host -ForegroundColor Green ("`nInstallation of Windows Subsystem for Linux (WSL), $distroName Linux is complete")
43
44# Configure user for WSL Distro
45Write-Host -ForegroundColor Yellow ("`nConfiguring user:$user for Windows Subsystem for Linux (WSL), $distroName Linux")
46Write-Host -ForegroundColor Yellow ("`nSet password for $user when prompted")
47Start-Process $wslPath\$wslDistro -ArgumentList "run adduser $user --shell bash --uid 1000" -NoNewWindow -Wait
48Start-Process $wslPath\$wslDistro -ArgumentList "run echo '$user ALL=(ALL) ALL' >> /etc/sudoers" -NoNewWindow -Wait
49Start-Process $wslPath\$wslDistro -ArgumentList "config --default-uid 1000" -NoNewWindow -Wait
50Start-Process $wslPath\$wslDistro -ArgumentList "run echo export PLANTUML=/usr/local/plantuml.jar >> ~/.bash_profile"  -NoNewWindow -Wait # would like to add this to makefile
51Start-Process $wslPath\$wslDistro -ArgumentList "run echo neofetch >> ~/.bash_profile"  -NoNewWindow -Wait # would like to add this to makefile
52Start-Process $wslPath\$wslDistro -ArgumentList "run echo from pprint import pprint >> ~/.pyrc"  -NoNewWindow -Wait # would like to add this to makefile
53Start-Process $wslPath\$wslDistro -ArgumentList "run git config --global http.sslVerify false"  -NoNewWindow -Wait
54Start-Process $wslPath\$wslDistro -ArgumentList "run git config --global user.name $user"  -NoNewWindow -Wait
55Start-Process $wslPath\$wslDistro -ArgumentList "run git config --global user.email '$email'"  -NoNewWindow -Wait
56
57# Create desktop shortcut for user
58$WScriptShell = New-Object -ComObject WScript.Shell
59$Shortcut = $WScriptShell.CreateShortcut($ShortcutFile)
60$Shortcut.TargetPath = $TargetFile
61$Shortcut.Save()
62
63# Cleanup
64Remove-Item -Force $wslPath\rootfs.tar.gz
65Remove-Item -Force $wslPath\addWSLfeature.ps1
66Remove-Item -Force $wslPath\install.ps1
67
68Write-Host -ForegroundColor Green ("`nUser Configuration of user:$user for Windows Subsystem for Linux (WSL), $distroName Linux is complete")
69
70Stop-Transcript