towards automating documentation serving

ofloveandhate · Jul 11, 2024 · 604e5ff · 604e5ff
1 parent 74e95a9
commit 604e5ff
Show file tree

Hide file tree

Showing 15 changed files with 113 additions and 10 deletions.
diff --git a/.github/workflows/documentation.yml b/.github/workflows/documentation.yml
@@ -0,0 +1,27 @@
+name: documentation
+
+on: [push, pull_request, workflow_dispatch]
+
+permissions:
+  contents: write
+
+jobs:
+  docs:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+      - name: Install dependencies
+        run: |
+          pip install sphinx sphinx_rtd_theme myst_parser
+      - name: Sphinx build
+        run: |
+          sphinx-build doc _build
+      - name: Deploy to GitHub Pages
+        uses: peaceiris/actions-gh-pages@v3
+        if: ${{ github.event_name == 'push' && github.ref == 'refs/heads/main' }}
+        with:
+          publish_branch: gh-pages
+          github_token: ${{ secrets.GITHUB_TOKEN }}
+          publish_dir: _build/
+          force_orphan: true
diff --git a/docs/Makefile → doc/Makefile b/docs/Makefile → doc/Makefile
diff --git a/docs/conf.py → doc/conf.py b/docs/conf.py → doc/conf.py
diff --git a/docs/index.rst → doc/index.rst b/docs/index.rst → doc/index.rst
diff --git a/doc/making_links_to_existing_content.rst b/doc/making_links_to_existing_content.rst
@@ -0,0 +1,57 @@
+🔗 Making links to existing content
+===================================
+
+* You can use either markdown style links, or html style links.  
+* Specify the type of content to which you are linking by preceding the name of the content with that type.
+* 
+
+Link to an assignment
+-----------------------
+
+
+To link to an existing Canvas assignment, use a link of the form
+
+.. code-block:: 
+	
+	<a href="assignment:Test Assignment">link to Test Assignment</a>
+	[Test Assignment](assignment:Test Assignment)
+
+The name must match exactly, including case.  This is the name on Canvas, not the name of the containerized content on your local computer.  That is, the thing after `assignment:` is the `name` field from `meta.json`.
+
+Link to a page
+-----------------------
+
+To link to an existing Canvas page, use a link of the form
+
+.. code-block:: 
+
+	<a href="page:Test Page">Link to page titled Test Page</a>
+	[Link to page titled Test Page](page:Test Page)
+
+The name must match exactly, including case.  This is the name on Canvas, not the name of the containerized content on your local computer.  That is, the thing after `page:` is the `name` field from `meta.json`.
+
+
+Link to an uploaded file
+-------------------------------
+To link to an existing Canvas file, use a link of the form
+
+.. code-block:: 
+
+	<a href="file:DavidenkoDiffEqn.pdf">Link to file called DavidenkoDiffEqn.pdf</a>
+	[Link to file called DavidenkoDiffEqn.pdf](file:DavidenkoDiffEqn.pdf)
+
+The name must match exactly, including case.  This is the name of the file on Canvas.  There is currently no way to refer to multiple files of the same name in different folders on Canvas.  If you want this, make an issue, or implement it yourself and make a PR.
+
+
+
+Notes
+------
+
+What if the content doesn't (yet) exist?
+******************************************
+
+If the "existing" content doesn't yet exist when the content is published, a broken link will be made, and a warning issued to the terminal.  This is ok.  Think of the publishing process using Markdown2Canvas similar to the compilation of a TeX document, which is done in multiple passes.  Once the page / assignment / file exists, the link will resolve correctly to it.  Publish all content about twice to get links to resolve.
+
+
+
+
diff --git a/docs/markdown2canvas.rst → doc/markdown2canvas.rst b/docs/markdown2canvas.rst → doc/markdown2canvas.rst
diff --git a/docs/on_meta_dot_json.rst → doc/on_meta_dot_json.rst b/docs/on_meta_dot_json.rst → doc/on_meta_dot_json.rst
diff --git a/docs/tutorials/making_your_first_course.rst → doc/tutorials/making_your_first_course.rst b/docs/tutorials/making_your_first_course.rst → doc/tutorials/making_your_first_course.rst
@@ -4,20 +4,29 @@ Making and publishing your first course using `markdown2canvas`
 
 A course that uses `markdown2canvas` is just a folder on your computer, with a bit of extra structure.  (Ideally, you should turn it into a git repository and use version control.)
 
-The folder has some special structure.  I'll take you through it in stages.
+The folder has some special structure.  I'll take you through it in stages.  You can also copy the directory from the `examples/` folder in the repo if you don't want to go through it in steps.
 
 
+Create a course folder
+----------------------------
+
+Courses in markdown2canvas are contained in a folder.  The name of the folder is arbitrary.  🎯 Make a folder called `course_folder`.  Call it whatever you want, but below I'll call it `course_folder`.
+
 Create the course metadata
 ----------------------------
 
+🎯 Make a folder called `_course_metadata`.  The name of this folder matters.  (I use leading underscores to denote things never published or that aren't Canvas content.)
+
+🎯 Make two files therein, `defaults.json` and `replacements.json`.  Here's a picture of the directory structure after this step:
+
 .. code-block:: 
 
 	course_folder/
 	course_folder/_course_metadata/                   # must be named _course_metadata
 	course_folder/_course_metadata/defaults.json      # must be named defaults.json
 	course_folder/_course_metadata/replacements.json  # <--- replacements.json is arbitrary.  change in `defaults.json`
 
-And that's all that's really required.  🎯 Here's some starter contents:
+🎯 Here's some starter contents for you to copy into those two files.
 
 
 `defaults.json`:
@@ -138,11 +147,27 @@ Pages and Assignments must have a `source.md` file.  It's markdown, and can incl
 Add a file for students to download
 -------------------------------------
 
-We're going to make a link to a file in the module for Lesson 1, and we also make a link to this file in the assignment we created.  
+We're going to make a link to a file in the module for Lesson 1, and we also make a link to this file in the assignment we created.  Here's the new structure after this step:
+
+.. code-block:: 
+
+	course_folder/
+	course_folder/_course_metadata/...                 
+
+	course_folder/_styles/generic/...
+
+	course_folder/Lesson1/readings.page/...
+	course_folder/Lesson1/assignment1.assignment/...
+
+	course_folder/Lesson1/ring.stl
+	course_folder/Lesson1/ring.file/
+	course_folder/Lesson1/ring.file/meta.json
+
+
 
 🎯 Make a file in `Lesson1/` called `ring.stl`.  The contents of this file are arbitrary.
 
-🎯 Make a new folder in `Lesson1`, and call it `ring.file`.  Make a file in there called `meta.json`.  
+🎯 Make a new folder in `Lesson1`, and call it `ring.file`.  Make a file in there called `meta.json`. Here are some contents for you to copy-paste. 
 
 `ring.file/meta.json`
 

diff --git a/docs/tutorials/publishing_content.rst → doc/tutorials/publishing_content.rst b/docs/tutorials/publishing_content.rst → doc/tutorials/publishing_content.rst
diff --git a/docs/tutorials/setup_mac_linux.rst → doc/tutorials/setup_mac_linux.rst b/docs/tutorials/setup_mac_linux.rst → doc/tutorials/setup_mac_linux.rst
diff --git a/docs/tutorials/setup_windows.rst → doc/tutorials/setup_windows.rst b/docs/tutorials/setup_windows.rst → doc/tutorials/setup_windows.rst
diff --git a/docs/tutorials/styling_content.rst → doc/tutorials/styling_content.rst b/docs/tutorials/styling_content.rst → doc/tutorials/styling_content.rst
diff --git a/docs/tutorials/text_replacements.rst → doc/tutorials/text_replacements.rst b/docs/tutorials/text_replacements.rst → doc/tutorials/text_replacements.rst
diff --git a/docs/tutorials/writing_content.rst → doc/tutorials/writing_content.rst b/docs/tutorials/writing_content.rst → doc/tutorials/writing_content.rst
diff --git a/docs/making_links_to_existing_content.rst b/docs/making_links_to_existing_content.rst