Is there a way to support custom directives? about sphinx-markdown-builder

[ocayrol]

You can have a look at https://www.sphinx-doc.org/en/master/development/tutorials/todo.html to see a little example.
The link you posted above ( https://github.com/ankita240796/docs/blob/f57ebfbb3dc82b256334efbf6a697ef612b36890/video.py ) is another example.

Inside a Sphinx extension, you define a new directive that will create a new type of node inside the document tree. Thus, you also define a new node class in the extension. Of course, you now have to explain how you would transform this new type of node into HTML, Latex or, here, Markdown. So, you write several "functions" that can transform this type of node into an output format. These functions will be dynamically weaved into a node visitor as visit / depart methods (so you need a visit function and a depart function and you have to be compliant with the node visitor internal behaviour). When you register the new type of node in the Sphinx application with the add_node method, you also give the visit / depart functions for each format you want to support.

In the "todo" tutorial, this is what is done for the todo node. In the "video" example, this is also what is done for the video_node.

[clayrisser]

@Tilix4 could you give a more detailed example of what you are referring to?

[Tilix4]

Hi @codejamninja , something like https://github.com/ankita240796/docs/blob/f57ebfbb3dc82b256334efbf6a697ef612b36890/video.py

This allows you to set a:

.. video:: /path/to/video.vid
   :options:

As we create html content with directives, it could be nice that your builder takes directly the raw html content to insert it in MD ouput (AFAIK it's fully supported) before designing a custom export.

[clayrisser]

Want to take a stab at it? The code to build it up is in this file.

https://github.com/codejamninja/sphinx-markdown-builder/blob/master/sphinx_markdown_builder/markdown_writer.py

[Tilix4]

I'll look into it, do you have any idea about the name of the function to handle any directive?

visit_directive() ?

[clayrisser]

I do not. I have not worked with custom directives.

[ocayrol]

I've just proposed a PR that will allow the addition of custom functions for transforming your custom nodes when you define your extension. I don't know if it will solve all the problems described in this issue but, in my opinion, it is a first step.

[clayrisser]

I just accepted the merge request. I'll release a new version this week.

[Tilix4]

That seems nice but I don't really get all the possibilities? Will you provide some code examples?