Markdown formatting rendering is incorrect on readthedocs compared to github/local editor.

[LexiconCode]

Details

• Read the Docs project URL: https://caster.readthedocs.io/en/latest/readthedocs/Customize_Caster/Creating_Hooks_and_Events/

Tested mkdocs v1.0.4 Python 2.7 mkdocs v1.1 Python 3.8

Expected Result

Markdown should render and display as it does in the local editor or on GitHub

Actual Result

Bullet points and Numbered lists don't always display correctly.

The following text is how the markdown should render.

Creating Hooks and Events

Hooks are a new concept to Caster 1.x.x. The basic idea is that Caster itself defines "events." Event objects contain immutable information about the stuff going on in the "guts" of Caster. Those objects are fed to "hooks", user-defined listeners, which can do whatever they want with that event data.

Hooks and Events make use of dependency injection and class inheritance through base classes. This design pattern coupled with loosely coupled code leads to less bugs and more productivity, and so the use of hooks rather than "guts" modifications is encouraged whenever possible. This should allow a decent amount of customization to happen without needing to make changes in the "guts" (Nexus, GrammarManager, CCRMerger, etc. of Caster.

All new hooks are set to false by default unless they're defined as defaults in settings.toml under default_hooks.

1. Hook Runner Placement

   First to figure out what data you want to monitor In the source code and create a hook runner. For example printer hook monitors Enabled/Disabled rules states. See grammar_manager.py. A hook runner runs every time an event occurs. Printer Hook runner example self._hooks_runner.execute(RuleActivationEvent(class_name, enabled)) .

   The Anatomy of hook runner:

   • self._hooks_runner.execute: executes the event as a hook runner

   • RuleActivationEvent: class name is the reference to the Event.

   • (class_name, enabled): event data are variables from source code captured by the Event.

   Note: Hook Runners can be reused to capture data throughout the source code in multiple functions assuming the observed data uses the same variables.

2. Create a Event

   Create a Event and add to Event types.

   • Events/Event types can be reused in hooks.

   • Don't forget to import the event at the location of your hook runner.

The event needs class name RuleActivationEvent, event type EventType.ACTIVATION , and the variables (class_name, enabled).

from castervoice.lib.merge.ccrmerging2.hooks.events.base_event import BaseHookEvent
from castervoice.lib.merge.ccrmerging2.hooks.events.event_types import EventType

class RuleActivationEvent(BaseHookEvent):
    def __init__(self, rule_class_name, active):
        super(RuleActivationEvent, self).__init__(EventType.ACTIVATION)
        # Data from the hook runner
        self.rule_class_name = rule_class_name 
        self.active = active 

3. Create a Hook.

Hooks need class name PrinterHook, Event type EventType.ACTIVATION and a pronunciation"printer"

Hook can be enabled/disabled while Caster is running. The get_pronunciation Is returned as printer

---

How it actually displays on readthedocs.io

[stsewd]

@LexiconCode I saw you added a configuration file to your project now, if you are still having this problem, please pin the mkdocs version to the one that's working locally https://github.com/dictation-toolbox/Caster/blob/c1e7a527f5a77b9337bd216d4cef3f227ff42b2d/docs/build/requirements.txt#L5

We install 0.17.3 as default

[LexiconCode]

I've tested with minimal edits to mkdocs.yml. e.g. pages: from nav: There's only so much time for me to go back so many versions.

Testing procedure:

1. pip install mkdocs==x.xx.x
2. mkdocs serve
3. Check documentation in question
4. pip uninstall mkdocs-bootswatch mkdocs-bootstrap mkdocs -y
5. Rinse and repeat for each mkdocs version

Notes

• The earliest mkdocs for the Python 3.8.2 is mkdocs 0.17.5 has the issue described in the OP.
• I've tried different browsers
• Python 2.7.X mkdocs 0.17.0 has the issue described in the OP.

[stale[bot]]

This issue has been automatically marked as stale because it has not had recent activity. It will be closed if no further activity occurs. Thank you for your contributions.

[LexiconCode]

What other information can I provide?

[humitos]

We don't do anything special regarding the parser. @LexiconCode did you try pinning all the versions you have installed locally to be installed on Read the Docs as well? (that includes mkdocs, the theme, etc)

Can you link the URL of the .md file in your repository that you are rendering? Also, the URL of the rendered version under Read the Docs.

[stale[bot]]

This issue has been automatically marked as stale because it has not had recent activity. It will be closed if no further activity occurs. Thank you for your contributions.

[LexiconCode]

Can you link the URL of the .md file in your repository that you are rendering?

https://github.com/dictation-toolbox/Caster/blob/master/docs/readthedocs/Customize_Caster/Creating_Hooks_and_Events.md

Also, the URL of the rendered version under Read the Docs.

https://caster.readthedocs.io/en/latest/readthedocs/Customize_Caster/Creating_Hooks_and_Events/

[LexiconCode]

@humitos thank you for your thoughts. Could you try copying pasting .md files and see if you can replicate the issue? It should be a fairly quick thing to do via mkdocs serve

[stale[bot]]

This issue has been automatically marked as stale because it has not had recent activity. It will be closed if no further activity occurs. Thank you for your contributions.

[LexiconCode]

This is still an issue.

[stsewd]

I'm able to replica this locally in a clean environment

So isn't a problem with rtd itself but a dependency/mkdocs

[LexiconCode]

That's great news, thank you! There are few other places in the Caster docs where this is an issue. If more reference materials for the issue needed let me know.

[stsewd]

@LexiconCode you should be able to reproduce this locally and report to mkdocs. I tested this in fedora 32, python 3.8 with the version of mkdocs in your requirements file.

pip install -r docs/build/requirements.txt
mkdocs build

[stsewd]

Closing as this doesn't look like a problem with rtd itself