question-mark
Stuck on an issue?

Lightrun Answers was designed to reduce the constant googling that comes with debugging 3rd party libraries. It collects links to all the places you might be looking at while hunting down a tough bug.

And, if you’re still stuck at the end, we’re happy to hop on a call to see how we can help out.

Is Restructured Text supported ?

See original GitHub issue

Thanks a lot for this package. I just came across it today and love the way it simplifies the documentation generation. As I attempted to test a few things, I ran into a question and hoping you can help clarify it.

  • Project Structure
Project Name 
   docs 
      doc_test.md 
   src  
      doc_test.py 
  • mkdocs.yml configuration file contents
site_name: Project Name
nav:
    - Home: index.md
    - About: about.md
    - Code Reference:
        - DocTest: doc_test.md
plugins:
    - search
    - mkdocstrings
theme: "material"
- *mkdocstrings* version: 0.15.

All of the code in the package that I am developing has docstrings in restructured text format. I noticed that version 0.15 has started to offer support for restructured text. I am not clear what is meant by this:

reStructuredText-style sections support in docstrings: pytkdocs understands all the reStructuredText fields, and returns structured data for mkdocstrings to render them. Note: only RST style is supported, not the whole markup.

Here is my script:

from random import randrange
from importlib.metadata import version

version('mkdocstrings')


# User Inputs
length_of_list = 10
my_list = [randrange(0, 100) for x in range(0, length_of_list)]


def add_list_restructured_text_doc_style(input_list: list) -> float:
    """Calculates the sum of the items in the list

    :param input_list: items to be summed
    """
    return float(sum(input_list))


def add_list_google_doc_style(input_list: list) -> float:
    """
    Calculates the sum of the items in the list.

    Args:
        input_list: items to be summed

    Returns:
        Sum of the elements of the list
    """
    return float(sum(input_list))

image

Issue Analytics

  • State:closed
  • Created 2 years ago
  • Reactions:1
  • Comments:5 (3 by maintainers)

github_iconTop GitHub Comments

6reactions
oprypincommented, May 3, 2021

Apologies, it’s hard to find in the docs: you need to explicitly select this non-default docstring style.

https://mkdocstrings.github.io/handlers/python/#selection

plugins:
  - mkdocstrings:
      handlers:
        python:
          selection:
            docstring_style: restructured-text
2reactions
sambafallcommented, Dec 21, 2022

docstring_style is implemented, and used as before, except for the restructured-text style which is renamed sphinx.

so instead of : docstring_style: restructured-text

now it is : docstring_style: sphinx

https://mkdocstrings.github.io/handlers/overview/

Read more comments on GitHub >

github_iconTop Results From Across the Web

reStructuredText - Docutils
reStructuredText is designed for extensibility for specific application domains. The reStructuredText parser is a component of Docutils.
Read more >
reStructuredText - Wikipedia
In this sense, reStructuredText is a lightweight markup language designed to be both (a) processable by documentation-processing software such as Docutils, and ...
Read more >
reStructuredText - Sphinx documentation
reStructuredText (reST) is the default plaintext markup language used by both Docutils and Sphinx. Docutils provides the basic reStructuredText syntax, while ...
Read more >
reStructuredText support | PyCharm Documentation - JetBrains
In addition to the support for reStructuredText Docstring Format (PEP 287), PyCharm provides a handy editor for restructured text.
Read more >
Introduction to reStructuredText - Write the Docs
reStructuredText is a lightweight markup language, so it's easier to read in plain-text format compared to heavier markup languages like DITA and other...
Read more >

github_iconTop Related Medium Post

No results found

github_iconTop Related StackOverflow Question

No results found

github_iconTroubleshoot Live Code

Lightrun enables developers to add logs, metrics and snapshots to live code - no restarts or redeploys required.
Start Free

github_iconTop Related Reddit Thread

No results found

github_iconTop Related Hackernoon Post

No results found

github_iconTop Related Tweet

No results found

github_iconTop Related Dev.to Post

No results found

github_iconTop Related Hashnode Post

No results found