MyST-Parser icon indicating copy to clipboard operation
MyST-Parser copied to clipboard

📚 Add a page on how to write sphinx extensions

Open chrisjsewell opened this issue 1 year ago • 0 comments

I think it would be nice in the documentation here, to have a brief section about extending sphinx:

  1. How to do some "quick and dirty" things in your conf.py with the def setup(app: Sphinx) "hook" (e.g. as I have very much done in https://github.com/executablebooks/MyST-Parser/blob/01c7565bd55ccabab065e18f40b0d09ace984457/docs/conf.py#L209)
  2. Then possibly about how you might want to later extract this into a "fully fledged" extension package

Obviously we don't want to rehash, what is already in sphinx: https://www.sphinx-doc.org/en/master/development/index.html, but

  • It maybe does still leave a little to be desired, in introducing the subject to beginners (https://github.com/sphinx-doc/sphinx/issues/9165)
  • There is some "RST first" wording in there

@choldgraf I know you have written a few things about this in your blog (https://chrisholdgraf.com/blog/2023/social-directive/) I wonder if you would be willing to add a little something here 😬 ?

chrisjsewell avatar Mar 02 '23 16:03 chrisjsewell