deploy: efd2487

_sources/canvas_objects.rst.txt

@@ -0,0 +1,50 @@
+Concrete Classes for Canvas Objects
+--------------------------------------
+
+
+
+.. autoclass:: markdown2canvas.Page
+   :members:
+   :undoc-members:
+
+
+.. autoclass:: markdown2canvas.Assignment
+   :members:
+   :undoc-members:
+
+.. autoclass:: markdown2canvas.Image
+   :members:
+   :undoc-members:
+
+
+.. autoclass:: markdown2canvas.Link
+   :members:
+   :undoc-members:
+
+
+.. autoclass:: markdown2canvas.File
+   :members:
+   :undoc-members:
+
+
+.. autoclass:: markdown2canvas.BareFile
+   :members:
+   :undoc-members:
+
+
+
+
+
+
+
+Base Classes
+--------------
+
+.. autoclass:: markdown2canvas.canvas_objects.CanvasObject
+   :members:
+   :undoc-members:
+
+
+.. autoclass:: markdown2canvas.canvas_objects.Document
+   :members:
+   :undoc-members:

_sources/emoji.rst.txt

@@ -0,0 +1,16 @@
+🙂 Emojification
+==================
+
+
+This library supports the automatic conversion of shortcodes to emoji.  During translation from local file to Canvas content, `markdown2canvas` will attempt to emojize your text from "shortcodes".  
+
+* You may also just use emoji directly without using short codes.  
+* We felt that also allowing short codes would be helpful.
+
+For example, `:open_book:` goes to 📖.  
+
+* We use the `emoji` library to do this.  Here's `a link to their documentation <https://pypi.org/project/emoji/>`_.
+* `Shortcodes can be found here <https://carpedm20.github.io/emoji/>`_.
+
+Right now, emoji shortcodes can only be used in content, not in names of things -- shortcodes in names will not be emojized.
+

_sources/exceptions.rst.txt

@@ -0,0 +1,14 @@
+Exceptions
+-------------
+
+.. autoclass:: markdown2canvas.exception.AlreadyExists
+   :members:
+   :undoc-members:
+
+.. autoclass:: markdown2canvas.exception.SetupError
+   :members:
+   :undoc-members:
+
+.. autoclass:: markdown2canvas.exception.DoesntExist
+   :members:
+   :undoc-members:

_sources/free_functions.rst.txt

@@ -0,0 +1,30 @@
+Free functions
+=====================
+
+
+Setup functions
+-------------------
+
+.. automodule:: markdown2canvas.setup_functions
+   :members:
+
+
+
+Functions for interacting with a course on Canvas
+---------------------------------------------------
+
+.. automodule:: markdown2canvas.course_interaction_functions
+   :members:
+
+
+Functions markdown2canvas uses to translate from markdown to Canvas-html
+--------------------------------------------------------------------------
+
+.. automodule:: markdown2canvas.translation_functions
+   :members:
+
+.. autofunction:: markdown2canvas.canvas_objects.find_local_images
+
+.. autofunction:: markdown2canvas.canvas_objects.find_local_files
+
+

_sources/gotchas.rst.txt

@@ -0,0 +1,12 @@
+💥 Gotchas
+===========
+
+
+There are some idiosyncrasies in `markdown2canvas`.  This page is me doing my best to share them with you.
+
+
+
+Markdown lists and enumerations
+----------------------------------
+
+Markdown lists and enumerations MUST have a newline above them.  If your list / enumeration doesn't render correctly on Canvas, then it probably needs a newline above it.

_sources/history.rst.txt

@@ -0,0 +1,47 @@
+Why this library exists
+========================
+
+(This is silviana amethyst writing.)
+
+Why I wrote/maintain this library
+-------------------------------------
+
+The particular problem this library solves is that of putting Canvas content under version control, and also using Markdown for that content.  Canvas pages are not well-suited to version control *per se*, because they live on the LMS.  I wanted local files, with repos I can share with other designers and instrutors.  
+
+Further, I wanted to be able to find-and-replace across many pieces of Canvas content at once.  Local files with my editor of choice is the way to do that; it's impossible on Canvas.  Hence, this library.
+
+Additionally, uniform appearance and ability to change much with little effort.  I wrote a "style" system that puts headers and footers around my content, eliminating repetitive and error-prone work.  Want emester-specific text at the top of all your content?  Trivial with `markdown2canvas`: just change the header file, re-publish, and do something better with your time than wait for the stupid Canvas editor to load.
+
+A secondary problem this library solves is that of images.  Images on Canvas are bare, and it's easy to end up with duplicate versions, as well as not have alt text.  By using markdown/html under version control, I can write my alt text directly into page source, instead of using the crappy click-heavy interface on Canvas.  
+
+
+I've successfully automated many mundane and error-prone tasks using this library, including:
+
+* Automating creation of Canvas assignments for the Webwork homework system
+* Consistent and flexible styling and beautification of content across an entire course
+
+The cost of development and maintenance has paid itself off many times over, both in terms of mental load and time savings.
+
+
+History 2021-2024
+-----------------------
+
+I (silviana) started writing this library in 2021 to meet the needs of a new course at UWEC, DS150: Computing in Python: Fundamentals and Procedural Programming.  I also anticipated using it for the upcoming 2022 re-design of DS710, Programming for Data Science at UWEC/UW Extended Campus.  
+
+Mckenzie started contributing to `markdown2canvas` in 2022 during that DS710 re-design, and she really ran with it as she applied it to her math courses.  Mckenzie added significant features to this library, including
+
+* links to existing pages, assignments, quizzes, and files
+* warnings when some content doesn't exist
+* clarifications and consistency across parts of the library
+* bugfixes
+
+
+Allison contributing to the library in summer 2024 as silviana prepared to move to MPI, contributing:
+
+* improved unit testing
+* documentation, particularly tutorials and notes
+* finding more bugs and gotchas
+
+As I move to new things in August 2024, I wish you well.  
+
+

_sources/index.rst.txt

@@ -12,7 +12,7 @@ This is the documentation for `markdown2canvas`, a Python library for containeri
    :maxdepth: 2
    :caption: Contents:
 
-Tutorials
+Tutorials 👩‍🏫
 ================
 
 .. toctree::
@@ -24,36 +24,55 @@ Tutorials
    tutorials/writing_content
    tutorials/styling_content
    tutorials/text_replacements
+   tutorials/uploading_files
    tutorials/publishing_content
+   tutorials/markdown_python_extensions
 
 
 
-Notes
-========
+Usage notes
+=================================
 
 .. toctree::
-   :maxdepth: 1
+   :maxdepth: 2
    :caption: Some useful notes on aspects of using the library
 
+   gotchas
+   emoji
    on_meta_dot_json
+   markdown_1
    making_links_to_existing_content
-   wishlist
 
 
-Useful links
-==============
+
+
+
+
+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.  
 
 
 
+Implementation notes
+=======================
+
+.. toctree::
+   :maxdepth: 1
+   :caption: Notes about library implementation
+
+   wishlist
+   unit_tests
+   history
+
+
 Details 📝
 ================
 
 .. toctree::
-   :maxdepth: 0
-   :caption: Contents:
+   :maxdepth: 1
 
    markdown2canvas
 

_sources/making_links_to_existing_content.rst.txt

@@ -1,9 +1,15 @@
 🔗 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.
-* 
+
+Notes for links to all content types
+----------------------------------------
+
+* You can use either markdown style links, or html style links.  Below, I'll give examples using both syntaxes.
+* Specify the type of content to which you are linking by preceding the name of the content with that type.  
+
+    * For example, `assignment:Test Assignment` will make a link to the assignment with name `Test Assignment`.
+
 
 Link to an assignment
 -----------------------
@@ -14,7 +20,8 @@ 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)
+
+	[link to 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`.
 
@@ -26,6 +33,7 @@ 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`.
@@ -38,14 +46,15 @@ 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
-------
+Notes about making links
+--------------------------
 
 What if the content doesn't (yet) exist?
 ******************************************

_sources/markdown2canvas.rst.txt

@@ -8,5 +8,18 @@ This is the detailed list of all functions and types available in the library.
 Python libraries used: `canvasapi`
 
 
-.. automodule:: markdown2canvas
-   :members:
+
+.. toctree::
+   :maxdepth: 2
+
+   canvas_objects
+   exceptions
+   free_functions
+
+
+
+
+
+
+
+

_sources/markdown_1.rst.txt

@@ -0,0 +1,5 @@
+Making sure markdown renders when there is a <div>
+===================================================
+
+Any time you have a `<div>` (in a header, footer, body, etc.) make sure that the option `markdown="1"` is included. 
+Otherwise, markdown will not render properly on Canvas.