docs: draft sphinx migration doc

docs/_quarto.yml

@@ -66,6 +66,7 @@ website:
             - get-started/dev-renderers.qmd
         - section: "Extra Topics"
           contents:
+            - get-started/extra-migrating-sphinx.qmd
             - get-started/extra-build-sequence.qmd
 
 

docs/get-started/extra-migrating-sphinx.qmd

@@ -0,0 +1,145 @@
+---
+title: Migrating from Sphinx
+jupyter:
+  kernelspec:
+    display_name: Python 3 (ipykernel)
+    language: python
+    name: python3
+---
+
+Oftentimes, developers want to migrate from Sphinx to quartodoc without making lots of changes to existing docstrings.
+
+Suppose you have rst codeblocks in your docstring that you'd like to render:
+
+```{python}
+class MyClass:
+    """This is a great class
+
+    Examples
+    --------
+
+    ..code:: python
+
+        example_code = "here"
+
+    See Also
+    --------
+
+    :func:`float`
+
+    """
+
+    def __init__(self): ...
+
+```
+
+Note that the block above has rst directives for `.. code::`, and an rst interlink
+`` :func:`float` ``.
+
+
+## Manually changing rst to markdown
+
+A quick way to migrate to quartodoc, would be to change the rst directives (e.g. `.. code:: python`) to markdown:
+
+```python
+class MyClass:
+    """This is a great class
+
+    Examples
+    ========
+
+    ```python
+    example_code = "here"
+    ```
+
+    See Also
+
+    [](:func:`float`)
+
+    """
+```
+
+Note two important changes in the docstring above:
+
+1. The example code now uses a markdown code block (starting with ```` ``` ````).
+   You can also write the code in [docstring syntax or quarto blocks](./docstring-examples.qmd#examples-using-code-blocks).
+2. The See Also section is now formatted as markdown for the [interlinks filter](./interlinks.qmd).
+
+
+## Custom rendering of rst directives
+
+While changing all the restructured text in your docstrings to markdown gets the job done,
+it is often easier to use some code to make the changes first, and then edit the docstrings
+later.
+
+In order to convert your restructured text to markdown, you can define a custom renderer.
+
+### Using conversion functions
+
+For example:
+
+```{python}
+from quartodoc.experimental.sphinx_migration import (
+    convert_code_rst_to_md,
+    convert_rst_link_to_md
+)
+
+
+
+print(
+convert_code_rst_to_md("""
+..code:: 
+    example_code = "here"
+""")
+)
+```
+
+```{python}
+print(
+convert_rst_link_to_md(":func:`some_object`")
+
+)
+```
+
+### Extending a Renderer
+
+```{python}
+import re
+
+from quartodoc import MdRenderer, preview
+
+from plum import dispatch
+from griffe.docstrings import dataclasses as ds
+from quartodoc import ast as qast
+
+class MyRenderer(MdRenderer):
+    style = "my_renderer3"
+
+    @dispatch
+    def render(self, el: qast.ExampleText):
+        new_value = convert_code_rst_to_md(el.value)
+        return new_value
+
+    @dispatch
+    def render(self, el: qast.DocstringSectionSeeAlso):
+        return convert_rst_link_to_md(el.value)
+
+
+```
+
+### Testing docstrings
+
+```{python}
+from quartodoc.interactive import get_object_interactive
+
+mod = get_object_interactive(MyClass)
+obj = mod.members["MyClass"]
+
+
+print(
+    MyRenderer().render(obj)
+)
+
+
+```
+