Converting an old lesson

Convert a Jekyll lesson

This brings in the necessary files

Add the template lesson as a new remote:

git remote add s-l-t https://github.com/coderefinery/sphinx-lesson-template.git
git fetch s-l-t

Check out some basic files into your working directory. Warning: if you add a .github/workflows/sphinx.yml file, even a push to a branch will override github pages:

git checkout s-l-t/master -- requirements.txt
git checkout s-l-t/master -- .github/workflows/sphinx.yml

If you need more Sphinx files:

git checkout s-l-t/master -- content/conf.py
git checkout s-l-t/master -- .gitignore Makefile make.bat

If you need the full content (only index.rst for now):

git checkout s-l-t/master -- content/

(if jekyll conversion) Move content over:

git mv _episodes/* content/

(if jekyll conversion) Copy stuff from index.md into content/index.rst.

(if jekyll conversion) Remove old jekyll stuff:

git rm jekyll-common/ index.md _config.yml Gemfile .gitmodules

Set up github pages (first commit to trigger CI), see Installation:

git checkout -b gh-pages origin/gh-pages
git commit -m 'empty commit to trigger gh-pages' --allow-empty
git push

Do all the rest of the fixing… all the bad, non-portable, non-relative markdown and so on. This is the hard part. Common problems:

  • Non-consecutive section headings

  • Multiple top-level section headings (there should be one top-level section heading that is the page title)

  • Weird relative links (most work though)

You can also update your local view of the default branch:

git remote set-head origin --auto

Joint history

This option joins the histories of the two repositories, so that you could merge from the template repository to keep your files up to date. This may not currently work, and also may not have any value (but is kept here for reference until later).

Merge the two unrelated histories:

$ git remote add template https://github.com/coderefinery/sphinx-lesson-template
$ git fetch template
$ git merge template/master --allow-unrelated-histories
# Resolve any possible merge conflicts
$ git checkout --theirs .gitignore
$ git checkout --ours LICENSE
$ git add .gitignore LICENSE
$ git commit -m 'merge sphinx-lesson history to this lesson'

Then proceed like the previous section shows.