Working With An Existing Module Site¶

To edit and publish content on an existing curriculum site, make sure you have the necessary prerequisites and have set up Sphinx, as detailed in Setting Up A New Module Site.

Building the Site¶

Clone the repository and, from the project directory, verify that you can build the site.

$ ./build.sh
Running Sphinx v1.7.2
loading pickled environment... not yet created
building [mo]: all of 0 po files
building [html]: all source files
updating environment: 1 added, 0 changed, 0 removed
reading sources... [100%] index
looking for now-outdated files... none found
pickling environment... done
checking consistency... done
preparing documents... done
writing output... [100%] index
generating indices... genindex
writing additional pages... search
copying static files... done
copying extra files... done
dumping search index in English (code: en) ... done
dumping object inventory... done
build succeeded.

The HTML pages are in docs.

If the build script fails due to a permissions error, enable its executable bit:

$ chmod +x build.sh

The build script builds HTML files from the source Markdown and reStructuredText files, using a template. It places the built files in the /docs folder so they can be hosted via GitHub Pages.

Viewing the Site Locally¶

When updating a site, you should build and proof your changes locally before committing them. To do this, we’ll use Python’s http.server module.

macOS and Linux¶

Add the following line to your ~/.bash_profile (macOS) or ~/.bashrc (Linux):

alias serve='python -m http.server'

Open a second terminal window and navigate to the project’s /docs folder. Then run:

$ serve
Serving HTTP on 0.0.0.0 port 8000 (http://0.0.0.0:8000/) ...

You can now view the site at localhost:8000. You can rebuild the site in another window while the server is still running, and changes will be immediately reflected.

Windows¶

First check to make sure you have a ~/.bash_profile and a ~/.bashrc file, as most Windows machines do not automatically create these files. If they do not exist create them using the following commands:

$ touch ~/.bash_profile
$ touch ~/.bashrc

Now add the following line to your .bash_profile if it is not already there:

if [ -f ~/.bashrc ]; then
   source ~/.bashrc
fi

Then add the following line to your .bashrc file:

alias serve='python -m http.server'

Open a second terminal window and navigate to the project’s /docs folder. Then run:

$ serve

You can now view the site at localhost:8000. You can rebuild the site in another window while the server is still running, and changes will be immediately reflected.

Editing Documents¶

Sites build using the LaunchCode Sphinx site template may have source code in either Markdown (abbreviated MD, with extension .md) or reStructuredText (abbreviated RST, with extension.rst) formats.

Most LaunchCode Education sites rely primarily on RST, though in some cases it may be suitable to use MD source files.

reStructured Text¶

Pros¶

Table of contents generation
Built-in admonition (note, warning, etc) support
Support for cross-page references

Cons¶

More complicated syntax than MD
Less well-known among developers than MD
Table syntax is difficult to work with

Working with RST¶

reStructuredText can have a bit of a learning curve if you’re accustomed to Markdown. That said, once you get used to the basics it has definite advantages to using MD.

Read the Sphinx reStructuredText Primer, and bookmark it as a reference. A modest familiarity with RST with go a long way toward allowing you to create rich curriculum pages.

Here are a few things to note if you’re new to RST:

RST is sensitive to whitespace in some cases. For example, when using a directive, the contents of the directive must be indented to align with the directive name (usually 3 spaces).
Tables in RST require alignment of column contents and column-separators vertically. This is a common gotcha for those new to RST.
Headings do not require a specific character (as MD does with #). Instead, any text underlined by a repeated occurance of the same character will be a heading. The level of the heading is determined by the order of the character used in the doc.

For example:
- Level 1 Heading ===============
- Level 2 Heading —————
- Another Level 1 Heading =======================
- Level 3 Heading ^^^^^^^^^^
The RST and Sphinx Cheatsheet is a good resource for getting used to RST. Note that the rendered examples may look slightly different visually than those given due to differences between Sphinx templates.

When building a site with Sphinx, you are often given robust and descriptive warnings and errors. At first, these can seem daunting (“Why is Sphinx always yelling at me?!”) but paying attention to them can help you keep your markup code clean and avoid issues down the road.

Markdown¶

When setting up Sphinx via our instructions we had you install a Sphinx extension that enables support for CommonMark, a widely-used Markdown specificaion. Note that CommonMark does not include widely-used features such as table support, which are part of MD language extensions (e.g. GitHub Markdown).

Pros¶

Simple syntax
Is more widely known by developers than RST

Cons¶

Lacks several useful features supported by RST (see above)
CommonMark does not support tables

Working with Markdown¶

Many developers are already familiar with Markdown syntax. However, we still encourage all contributors to skim the CommonMark docs to make sure you’re using features built into CommonMark, which is a smaller spec than many others.

Tables¶

CommonMark does not directly support Markdown tables. It is possible to support Markdown tables in Sphinx via a source-translation approach (MD -> RST -> HTML). As of July 2018, this feature has not been implemented, and is in the template development backlog. If you absolutely need to use tables in your pages, we recommend using RST instead.

Site Style¶

When creating pages, use the Style Guide. This guide provides some basic conventions for improving the look and feel of curriculum sites, while providing for consistency across sites.

Deploying¶

Once you’ve made some changes to the site–edit, built, test, commit–you’re ready to deploy. How to do this depends on your role.

Non-Staff Contributions¶

For those not on the LaunchCode Education team, the recommended deployment mechanism is to create a pull request. This allows the team to review your changes, and to look for common formatting issues before deploying.

Note

Some course instructors and TAs may be granted direct commit access to course curriculum modules, based on the circumstances. If you would like direct commit access, talk to somebody on the Education team.

Staff Contributions¶

All Education Team staff should have push permission for the repositories that they’re working on. Pushing changes to the GitHub repo will automatically deploy the new files.

Warning

Changes to GitHub Pages sites can take several minutes to be reflected. If you push and don’t see your change, wait a few minutes and do a hard refresh of the page.