Merge pull request #31 from ofloveandhate/feature/summer2024

Feature/summer2024

.github/workflows/documentation.yml

@@ -0,0 +1,28 @@
+name: Sphinx build
+
+on: push
+
+permissions:
+  contents: write
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+    - uses: actions/checkout@v3
+
+    - name: Build HTML
+      uses: ammaraskar/sphinx-action@master
+
+    - name: Upload artifacts
+      uses: actions/upload-artifact@v3
+      with:
+        name: html-docs
+        path: docs/_build/html/
+
+    - name: Deploy
+      uses: peaceiris/actions-gh-pages@v3
+      if: github.ref == 'refs/heads/main'
+      with:
+        github_token: ${{ secrets.GITHUB_TOKEN }}
+        publish_dir: docs/_build/html

.gitignore

@@ -10,3 +10,6 @@ build/
 */*/result.html
 styled_source.md
 *.icloud
+
+_build/
+make.bat

README.md

@@ -276,38 +276,3 @@ You can hold links in modules under version control, similar to `Page` and `Assi
 ```
 
 
-
----
-
-# Future work ⚠️ this is not yet implemented in `mc`
-
-## Containerization of quizzess ⚠️ this is not yet implemented in `mc`
-
-I want this so badly, but I'm not up to it yet.  I'd love a contribution!
-
-## Due dates ⚠️ this is not yet implemented in `mc`
-
-
-Due dates are encoded relative to the first day of class, by week number and day of week.  Week numbers start at 1.
-
-| Day code | Day of week | 
-| --- | --- |
-| M | Monday |
-| T | Tuesday |
-| W | Wednesday |
-| R | Thursday |
-| F | Friday |
-| Sa | Saturday |
-| Su | Sunday |
-
-In the `meta.json` file for an assignment, the due date is encoded like this example:
-
-```
-"due":{"time":"10pm", "week":11, "day":"R"}
-```
-
-A default time for all assignents can be set in `_course_metadata/defaults.json` with entry `"due_time":"10pm"`, for example.  If this record is not present, and no due time is set for an individual assignment, then the Canvas default time for the course will be used.  On UWEC's system, this can be changed in the course settings. The default value is 11:59pm.
-
-The first day of class is set ...  HOW??
-
-

docs/Makefile

@@ -0,0 +1,20 @@
+# Minimal makefile for Sphinx documentation
+#
+
+# You can set these variables from the command line, and also
+# from the environment for the first two.
+SPHINXOPTS    ?=
+SPHINXBUILD   ?= sphinx-build
+SOURCEDIR     = .
+BUILDDIR      = _build
+
+# Put it first so that "make" without argument is like "make help".
+help:
+	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+
+.PHONY: help Makefile
+
+# Catch-all target: route all unknown targets to Sphinx using the new
+# "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
+%: Makefile
+	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)

docs/conf.py

@@ -0,0 +1,34 @@
+# Configuration file for the Sphinx documentation builder.
+#
+# For the full list of built-in configuration values, see the documentation:
+# https://www.sphinx-doc.org/en/master/usage/configuration.html
+
+# -- Project information -----------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information
+
+project = 'markdown2canvas'
+copyright = '2024, silviana amethyst, Mckenzie West, Allison Beemer'
+author = 'silviana amethyst, Mckenzie West, Allison Beemer'
+
+# -- General configuration ---------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration
+
+extensions = [
+    'sphinx.ext.autodoc',
+]
+
+templates_path = ['_templates']
+exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store']
+
+
+
+# -- Options for HTML output -------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output
+
+html_theme = 'bizstyle'
+html_static_path = ['_static']
+
+
+import os
+import sys
+sys.path.insert(0, os.path.abspath('../markdown2canvas/'))

docs/index.rst

@@ -0,0 +1,71 @@
+.. markdown2canvas documentation master file, created by
+   sphinx-quickstart on Wed Jul 10 13:17:30 2024.
+   You can adapt this file completely to your liking, but it should at least
+   contain the root `toctree` directive.
+
+`markdown2canvas`
+===========================================
+
+This is the documentation for `markdown2canvas`, a Python library for containerizing and publishing Canvas content.
+
+.. toctree::
+   :maxdepth: 2
+   :caption: Contents:
+
+Tutorials
+================
+
+.. toctree::
+   :maxdepth: 1
+
+   tutorials/setup_mac_linux
+   tutorials/setup_windows
+   tutorials/making_your_first_course
+   tutorials/writing_content
+   tutorials/styling_content
+   tutorials/text_replacements
+   tutorials/publishing_content
+
+
+
+Notes
+========
+
+.. toctree::
+   :maxdepth: 1
+   :caption: Some useful notes on aspects of using the library
+
+   on_meta_dot_json
+   making_links_to_existing_content
+   wishlist
+
+
+Useful links
+==============
+
+* `Canvas API documentation at root level <https://canvasapi.readthedocs.io/en/stable/>`_
+* `Canvas API class documentation <https://canvasapi.readthedocs.io/en/stable/class-reference.html>`_  I use this when chasing down how to set additional properties for various content types.  
+
+
+
+Details 📝
+================
+
+.. toctree::
+   :maxdepth: 0
+   :caption: Contents:
+
+   markdown2canvas
+
+
+Indices and tables
+==================
+
+* :ref:`genindex`
+* :ref:`modindex`
+* :ref:`search`
+
+Contact 📧
+=================
+
+If you have any questions or problems, please `submit an issue on github <https://github.com/ofloveandhate/markdown2canvas/issues>`_!

docs/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.
+
+
+
+

docs/markdown2canvas.rst

@@ -0,0 +1,12 @@
+
+
+markdown2canvas -- detailed documentation
+=============================================
+
+This is the detailed list of all functions and types available in the library.
+
+Python libraries used: `canvasapi`
+
+
+.. automodule:: markdown2canvas
+   :members:

docs/on_meta_dot_json.rst

@@ -0,0 +1,31 @@
+On the `meta.json` file
+=========================
+
+
+The `meta.json` file should be present in every containerized content folder.
+
+
+
+Valid properties
+-----------------
+
+Assignments
+*****************
+
+
+
+Pages
+******
+
+
+Links
+*******
+
+
+Files
+*******
+
+
+
+What happens if I specify a property / key that's not used or is invalid?
+-----------------------------------------------------------------------------

docs/requirements.txt

@@ -0,0 +1 @@
+canvasapi