From dba857e454ff8878084a81de72f31cf4c52e51de Mon Sep 17 00:00:00 2001 From: Michael Chow Date: Fri, 23 Jun 2023 13:20:52 -0400 Subject: [PATCH 1/2] docs: draft sphinx migration doc --- docs/_quarto.yml | 1 + docs/get-started/extra-migrating-sphinx.qmd | 81 +++++++++++++++++++++ 2 files changed, 82 insertions(+) create mode 100644 docs/get-started/extra-migrating-sphinx.qmd diff --git a/docs/_quarto.yml b/docs/_quarto.yml index da2fb407..c6a8bb51 100644 --- a/docs/_quarto.yml +++ b/docs/_quarto.yml @@ -62,6 +62,7 @@ website: - get-started/dev-renderers.qmd - section: "Extra Topics" contents: + - get-started/extra-migrating-sphinx.qmd - get-started/extra-build-sequence.qmd diff --git a/docs/get-started/extra-migrating-sphinx.qmd b/docs/get-started/extra-migrating-sphinx.qmd new file mode 100644 index 00000000..5f7e5251 --- /dev/null +++ b/docs/get-started/extra-migrating-sphinx.qmd @@ -0,0 +1,81 @@ +--- +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` + + """ +``` + + +## Changing rst to markdown + +A quick way to migrate it to quartodoc, would be to change the `.. code:: python` piece 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. + +For example: + +```python +from quartodoc import MdRenderer + +from plum import dispatch +from griffe.docstrings import dataclasses as ds + +class MyRenderer(MdRenderer): + def +``` From 963392966fd0c3a14c0319eda8426f7b0e93c1ea Mon Sep 17 00:00:00 2001 From: Michael Chow Date: Tue, 27 Jun 2023 12:07:39 -0400 Subject: [PATCH 2/2] DRAFT: sphinx doc --- docs/get-started/extra-migrating-sphinx.qmd | 82 ++++++++++++++++++--- 1 file changed, 73 insertions(+), 9 deletions(-) diff --git a/docs/get-started/extra-migrating-sphinx.qmd b/docs/get-started/extra-migrating-sphinx.qmd index 5f7e5251..537e3510 100644 --- a/docs/get-started/extra-migrating-sphinx.qmd +++ b/docs/get-started/extra-migrating-sphinx.qmd @@ -11,29 +11,35 @@ Oftentimes, developers want to migrate from Sphinx to quartodoc without making l Suppose you have rst codeblocks in your docstring that you'd like to render: -```python +```{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` ``. -## Changing rst to markdown -A quick way to migrate it to quartodoc, would be to change the `.. code:: python` piece to markdown: +## 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: @@ -47,7 +53,6 @@ class MyClass: ``` See Also - ======== [](:func:`float`) @@ -60,6 +65,7 @@ Note two important changes in the docstring above: 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, @@ -68,14 +74,72 @@ later. In order to convert your restructured text to markdown, you can define a custom renderer. +### Using conversion functions + For example: -```python -from quartodoc import MdRenderer +```{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): - def + 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) +) + + +``` +