new documentation pages, and improvements in linkage

docs/emoji.rst

@@ -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.
+

docs/gotchas.rst

@@ -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.

docs/history.rst

@@ -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.  
+
+

docs/index.rst

@@ -26,21 +26,28 @@ Tutorials
    tutorials/text_replacements
    tutorials/uploading_files
    tutorials/publishing_content
+   tutorials/markdown_python_extensions
 
 
 
+.. _Top_Notes:
+
 Notes
 ========
 
 .. toctree::
    :maxdepth: 1
    :caption: Some useful notes on aspects of using the library
 
+   gotchas
+   emoji
    on_meta_dot_json
    markdown_1
    making_links_to_existing_content
    wishlist
    unit_tests
+   history
+
 
 
 Useful links

docs/making_links_to_existing_content.rst

@@ -43,6 +43,7 @@ To link to an existing Canvas file, use a link of the form
 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.
 
 
+.. _Links_Notes:
 
 Notes
 ------

docs/tutorials/making_your_first_course.rst

@@ -192,7 +192,7 @@ I use a script to help me publish my content.  🎯 Let's add it:
 	course_folder/_tools/content_all            # a txt file with names of content folders
 
 
-Here's a script I use in DS710.  🎯 Copy-paste it.
+Here's a script I use in DS710.  🎯 Copy-paste it into `_tools/publish_ready_content.py`.
 
 
 .. literalinclude:: ../../example/starter_course/_tools/publish_ready_content.py
@@ -210,7 +210,12 @@ Note that you just list the folder, and `markdown2canvas` does all the work with
 Publish the content!!!!!
 --------------------------
 
-Now, assuming you've completed the setup steps (Mac/Linux: saving your API key and URL in a .py file, and specifying the name of the file via an environment variable called `CANVAS_CREDENTIALS_FILE`), you should be able to publish the content to your course. 
+Now, assuming you've completed the setup steps 
+
+* :doc:`setup_mac_linux` 
+* :doc:`setup_windows`
+
+you should be able to publish the content to your course. 
 
 🎯 Be sure you copied in your Canvas course number to the `_tools/publish_ready_content.py` script!
 

docs/tutorials/setup_mac_linux.rst

@@ -19,10 +19,10 @@ Canvas credentials, do not skip this
 You must define an environment variable called `CANVAS_CREDENTIAL_FILE`, which is the location of a `.py` file containing two variables:
 
 #. `API_URL` -- a string, the url of how to access your Canvas install.  
-	* At UW Eau Claire, it's `https://uweau.instructure.com/`.  
+	* At UW Eau Claire, it's `uweau.instructure.com <https://uweau.instructure.com>`_.  
 	* I cannot possibly tell you your url, but your local Canvas admin can.
 
-#. `API_KEY` -- a string, the key you can get from Canvas.  Here's [a link to a guide on how to generate yours](https://community.canvaslms.com/t5/Admin-Guide/How-do-I-obtain-an-API-access-token-in-the-Canvas-Data-Portal/ta-p/157).  Do not share it with anyone -- having only this one piece of data, anyone can act as you.  Protect it at least as much as you would any other password or sensitive information.
+#. `API_KEY` -- a string, the key you can get from Canvas.  Here's `a link to a guide on how to generate yours <https://community.canvaslms.com/t5/Admin-Guide/How-do-I-obtain-an-API-access-token-in-the-Canvas-Data-Portal/ta-p/157>`_.  Do not share it with anyone -- having only this one piece of data, anyone can act as you.  Protect it at least as much as you would any other password or sensitive information.
 
 Thus, you should have a Python script somewhere, like this:
 

docs/tutorials/styling_content.rst

@@ -1,3 +1,4 @@
+
 Styling Pages and Assignments
 ===============================
 
@@ -44,8 +45,8 @@ I hope they're self-documenting in purpose and content.  Here's what's in the `h
    <!-- Droplets elements and components -->
 
 
-Note the markdown="1" included in the <div> above. Any time you include a <div>, make sure that this appears. 
-Otherwise, markdown will not render.
+Note the `markdown="1"` included in the `<div>` above. Any time you include a `<div>`, make sure that this appears. 
+Otherwise, markdown inside that `div` will not get translated to HTML, and thus will look incorrect.  Unless, of course, you want raw markdown in your content, I could see some use-cases!
 
 The footer simply closes the `div` I opened in the header:
 

markdown2canvas/translation_functions.py

@@ -151,7 +151,8 @@ def get_default_replacements_name():
                                 helpstr='a path to a json file containing key:value pairs of text-to-replace.  this path should be expressed relative to the top course folder')
 
 
-default_markdown_extensions = ['codehilite','fenced_code','md_in_html','tables','nl2br']
+default_markdown_extensions = ['codehilite','fenced_code','md_in_html','tables','nl2br'] #: The default `markdown` extensions to use when translating from markdown to html during publishing
+
 def get_default_markdown_extensions():
     return get_default_property(key='markdown_extensions', 
                                 helpstr='a list of strings being extensions to the `markdown` library used to translate from markdown to html before uploading to canvas.',