diff --git a/.github/workflows/documentation.yml b/.github/workflows/documentation.yml new file mode 100644 index 0000000..6ace7a6 --- /dev/null +++ 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 \ No newline at end of file diff --git a/docs/Makefile b/doc/Makefile similarity index 100% rename from docs/Makefile rename to doc/Makefile diff --git a/docs/conf.py b/doc/conf.py similarity index 100% rename from docs/conf.py rename to doc/conf.py diff --git a/docs/index.rst b/doc/index.rst similarity index 100% rename from docs/index.rst rename to doc/index.rst diff --git a/doc/making_links_to_existing_content.rst b/doc/making_links_to_existing_content.rst new file mode 100644 index 0000000..1707168 --- /dev/null +++ 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:: + + link to Test Assignment + [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:: + + Link to page titled Test Page + [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:: + + Link to file called DavidenkoDiffEqn.pdf + [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 b/doc/markdown2canvas.rst similarity index 100% rename from docs/markdown2canvas.rst rename to doc/markdown2canvas.rst diff --git a/docs/on_meta_dot_json.rst b/doc/on_meta_dot_json.rst similarity index 100% rename from docs/on_meta_dot_json.rst rename to doc/on_meta_dot_json.rst diff --git a/docs/tutorials/making_your_first_course.rst b/doc/tutorials/making_your_first_course.rst similarity index 82% rename from docs/tutorials/making_your_first_course.rst rename to doc/tutorials/making_your_first_course.rst index 902d54b..1566b77 100644 --- a/docs/tutorials/making_your_first_course.rst +++ b/doc/tutorials/making_your_first_course.rst @@ -4,12 +4,21 @@ 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/ @@ -17,7 +26,7 @@ Create the 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 b/doc/tutorials/publishing_content.rst similarity index 100% rename from docs/tutorials/publishing_content.rst rename to doc/tutorials/publishing_content.rst diff --git a/docs/tutorials/setup_mac_linux.rst b/doc/tutorials/setup_mac_linux.rst similarity index 100% rename from docs/tutorials/setup_mac_linux.rst rename to doc/tutorials/setup_mac_linux.rst diff --git a/docs/tutorials/setup_windows.rst b/doc/tutorials/setup_windows.rst similarity index 100% rename from docs/tutorials/setup_windows.rst rename to doc/tutorials/setup_windows.rst diff --git a/docs/tutorials/styling_content.rst b/doc/tutorials/styling_content.rst similarity index 100% rename from docs/tutorials/styling_content.rst rename to doc/tutorials/styling_content.rst diff --git a/docs/tutorials/text_replacements.rst b/doc/tutorials/text_replacements.rst similarity index 100% rename from docs/tutorials/text_replacements.rst rename to doc/tutorials/text_replacements.rst diff --git a/docs/tutorials/writing_content.rst b/doc/tutorials/writing_content.rst similarity index 100% rename from docs/tutorials/writing_content.rst rename to doc/tutorials/writing_content.rst diff --git a/docs/making_links_to_existing_content.rst b/docs/making_links_to_existing_content.rst deleted file mode 100644 index 4410d12..0000000 --- a/docs/making_links_to_existing_content.rst +++ /dev/null @@ -1,6 +0,0 @@ -Making links to existing content -=================================== - - - -