This is a warning message, in red text and bolded, to warn anyone using the module that it is, for example, actively in development, not yet validated, etc. Warning messages are optional.
This text discusses how a module has been validated against other existing code or modules. This text is given a green font color and bolded. See how to bold and make text different colors in the Markdown code.
Here you write an introduction that discusses in slight detail the framework of this tutorial notebook. Here you may reference external works or websites on which pieces of your module rely. It is often helpful to include an enumerated algorithm to highlight this modules processes. Within the algorithm you may refer to where source code is implemented as a part of this module.
The entire </made_up>algorithm is outlined below, with NRPy+-based components highlighted in green.
Include information relevant to this subsection here.
You may include any number of items here within the first box of the tutorial notebook, but I suggest being minimalistic when you can. Other sections that have been included in other tutorial modules are as follows
When using a new type of notation for the first time within the NRPy+ tutorial, you may want to include some notes on that here.
This is a great place to list out the references you link to within the module with actual citations.
This notebook is organized as follows.
The Table of Contents (ToC) plays a significant role in the formatting of your module. The above ToC is for this module, but I have constructed it in a way such that you should see all of the important details for any module you need to write. If you choose to include a preliminaries section, enumerate it with the "0." All other sections, subsections, and sub-subsections can be enumerated with the 1. Jupyter/LaTex will handle their own numbering/lettering scheme. It is important when creating subsections and sub-subsections that you indent as seen in the Markdown code. The text colors vary for the level section you're assigning within the Markdown code. When writing within the brackets to specify a step number, the following scheme is to be used.
If for some reason you go more then three levels deep in your sectioning, I would suggest finding a way to reorganize your sectioning to prevent that, or ask Zach Etienne what the next level of labeling for Steps should be. We will talk about the other components within the Markdown Code for the ToC in Step 1.a. The only text within the ToC section of this module should be the ToC code itself and what precedes it.
I also suggest that the titles for the Steps you include here following the ":" match the titles you use throughout your module.
This section is a great chance to include textual verbiage that might have been too specific for the introduction section, but serves as a beneficial setup to the remainder of the module. For instance, you may want to define quantities here, express important equations, and so on. I suggest that the Preliminaries section not be followed by any Python code blocks, and remains simply a block of information for users to refer back to.
We have already within this template had to link to sources both internally within this module, externally to other components of the NRPy+ tutorial, as well as externally to additional web sources. The next few sections discuss how this is done. It is important to know that any linking is done by combining brackets and parentheses "[ ]()" with the desired input in each.
On another note, main sections like this have their titles preceded by a single #. As you will see, for every deeper layer of sectioning, an additional # is appended on, reducing the size of the text.
A great resource for how to construct a Table of Contents is: https://medium.com/@sambozek/ipython-er-jupyter-table-of-contents-69bb72cf39d3.
The Table of Contents is a family of internal links. To link internally we first have to specify an *anchor tag* which is the text within the parentheses of preceded by a # (See ToC Markdown code). For instance, the anchor tag for this subsection is internal_links. So, for a particular Step within the Table of Contents you specify the Step title in brackets (e.g., [Step 1.a]), appended by the anchor tag in parentheses preceded by a # (e.g., (#internal_links)), followed by a ":" and the Step description (e.g., : Internal linking with the Jupyter notebook, Table of Contents). Look at the Markdown code for the Table of Contents for a few examples.
Important Note: The anchor tags cannot be anything that you want. Anchor tags must be entirely lowercase and contain no spaces. Numbers are fine as well as underscores, but not capitalization. I suggest making the anchor tags have significant meaning to the section there tied to, instead of making one that reads "step1a". The reason I say this is because if you ever need to resection your module, the tags won't all need to be changed as well if you give each one a unique name.
All we have done so far is establish anchor tags and clickable links within the Table of Contents, but how do we establish the link to the specific section within the module? Opening up the Markdown code for this section you will see a line of code above the title, and a line of code directly below the title. These are the answers to the question. Each section requires these components to be included for both the Jupyter notebook and LaTex internal linking. Make sure the top line of the Markdown code has a space between it and the title. Similarly, the code directly beneath the title needs space below it as well, separated from the main body of text (see above in Markdown code).
Important Note: Links do not work unless the two sections which are linked have been run.
The Table of Contents is now linked to this section, and you may have already noticed that this section, and all others, are linked back to the Table of Contents using the Markdown code in line at the end of the section title. This is exceedingly convenient for modules of great length. It may also be convenient when you're in a particular subsection and you wish to just return to the header section. This is accomplished using a bracket parentheses []() pairing like so (see this in Markdown code). Go back to Step 1.
Lastly, you would more often than not write a code block below implementing what was discussed in this section. This isn't always necessary, some header sections plainly serve as a set up for subsections that will contain all of the necessary coding components.
# This is the code block corresponding to Step 1.a: Internal linking within the Jupyter notebook, Table of Contents
print("We have successfully learned how to code internal links using Markdown Linking Protocol!!!")
We have successfully learned how to code internal links using Markdown Linking Protocol!!!
To link outside of this particular module we still use bracket parentheses [ ]() pairings. Since the links are not internal, we no longer need the # symbol and anchor tags. Instead, you need an actual link. For instance, look at your Markdown code to see how we link this website to a line of text. Of course, web links will simply work on their own as a hyperlink, but often you may need to link to multiple external sources and do not want all of the individual addresses clogging up the body of your text.
# This is the code block for Step 1.b: External linking outside of Jupyter notebook
print("Be efficient in how you link external sources, utilize []() pairs!!!")
Be efficient in how you link external sources, utilize []() pairs!!!
Other useful external sources we would like to link to are the existing files/modules within NRPy+. To do this we again resort to the [ ]() pair. By simply typing the file name into the parentheses, you can connect to another tutorial module (see Markdown). To access a .py file, you want to type the command ../edit/ followed by the file location. For instance, here is the .py file for this notebook (see Markdown).
# This is the code block for Step 1.b.i: Linking to other files/modules within NRPy+
print("Template_Style_Guide.py is an empty file...")
Template_Style_Guide.py is an empty file...
The following code cell converts this Jupyter notebook into a proper, clickable $\LaTeX$-formatted PDF file. After the cell is successfully run, the generated PDF may be found in the root NRPy+ tutorial directory, with filename Tutorial-Template_Style_Guide.pdf (Note that clicking on this link may not work; you may need to open the PDF file through another means.)
Important Note: Make sure that the file name is right in all six locations, two here in the Markdown, four in the code below.
import cmdline_helper as cmd # NRPy+: Multi-platform Python command-line interface
cmd.output_Jupyter_notebook_to_LaTeXed_PDF("Tutorial-Template_Style_Guide")
Created Tutorial-Template_Style_Guide.tex, and compiled LaTeX file to PDF
file Tutorial-Template_Style_Guide.pdf