1. Forum
  2. Usenet
  3. COMP.LANG.PYTHON

  • Generating documentation with Sphinx

    From Jason Friedman@21:1/5 to All on Mon Aug 28 12:46:20 2023
    I have two questions, please (this is after reading https://docs.readthedocs.io/en/stable/guides/cross-referencing-with-sphinx.html#automatically-label-sections
    ).


    This is my project structure:

    my_project
    api
    stuff1.py
    stuff2.py
    lib
    stuff3.py
    stuff4.py
    main_application.py


    In my_project/main_application.py I have two functions:


    def construct_response(exit_code: int, message: str) -> Response:
    """
    Construct a Flask-suitable response

    :param exit_code: 0 or something else
    :param message: something useful
    :return: a Flask-suitable response
    """


    @app.route(f"/{version}/<page>", methods=[GET, POST])
    def serve(page) -> Response:
    """
    Do some stuff and return 200 or 500

    :param page: this is a REST endpoint we are advertising to callers
    :return: a Flask Response generated by construct_response
    """


    Question 1: how do I embed in the serve function docstring a link to the construct_response function?


    Question 2: how do I embed in, for example, lib/stuff3.py, a link to the construct_response function?


    I tried:
    :ref:`my_project/api/stuff1:construct_response`

    but that gives an undefined label warning.

    --- SoupGate-Win32 v1.05
    * Origin: fsxNet Usenet Gateway (21:1/5)
  • From Jason Friedman@21:1/5 to All on Mon Aug 28 13:39:40 2023

    def construct_response(exit_code: int, message: str) -> Response:
    """
    Construct a Flask-suitable response

    :param exit_code: 0 or something else
    :param message: something useful
    :return: a Flask-suitable response
    """


    @app.route(f"/{version}/<page>", methods=[GET, POST])
    def serve(page) -> Response:
    """
    Do some stuff and return 200 or 500

    :param page: this is a REST endpoint we are advertising to callers
    :return: a Flask Response generated by construct_response
    """


    Question 1: how do I embed in the serve function docstring a link to the construct_response function?


    Question 2: how do I embed in, for example, lib/stuff3.py, a link to the construct_response function?


    I tried:
    :ref:`my_project/api/stuff1:construct_response`

    but that gives an undefined label warning.


    I can answer my own Question 1:
    :func:`construct_response`

    --- SoupGate-Win32 v1.05
    * Origin: fsxNet Usenet Gateway (21:1/5)
  • From Jason Friedman@21:1/5 to jsf80238@gmail.com on Mon Aug 28 15:12:34 2023
    And I can answer my own Question 2: :func:`my_project.main_application.construct_response`

    On Mon, Aug 28, 2023 at 1:39 PM Jason Friedman <jsf80238@gmail.com> wrote:

    def construct_response(exit_code: int, message: str) -> Response:
    """
    Construct a Flask-suitable response

    :param exit_code: 0 or something else
    :param message: something useful
    :return: a Flask-suitable response
    """


    @app.route(f"/{version}/<page>", methods=[GET, POST])
    def serve(page) -> Response:
    """
    Do some stuff and return 200 or 500

    :param page: this is a REST endpoint we are advertising to callers
    :return: a Flask Response generated by construct_response
    """


    Question 1: how do I embed in the serve function docstring a link to the
    construct_response function?


    Question 2: how do I embed in, for example, lib/stuff3.py, a link to the
    construct_response function?


    I tried:
    :ref:`my_project/api/stuff1:construct_response`

    but that gives an undefined label warning.


    I can answer my own Question 1:
    :func:`construct_response`


    --- SoupGate-Win32 v1.05
    * Origin: fsxNet Usenet Gateway (21:1/5)
  • From Jason Friedman@21:1/5 to All on Mon Aug 28 15:13:06 2023
    def construct_response(exit_code: int, message: str) -> Response:
    """
    Construct a Flask-suitable response

    :param exit_code: 0 or something else
    :param message: something useful
    :return: a Flask-suitable response
    """


    @app.route(f"/{version}/<page>", methods=[GET, POST])
    def serve(page) -> Response:
    """
    Do some stuff and return 200 or 500

    :param page: this is a REST endpoint we are advertising to callers
    :return: a Flask Response generated by construct_response
    """


    Question 1: how do I embed in the serve function docstring a link to the
    construct_response function?


    Question 2: how do I embed in, for example, lib/stuff3.py, a link to the
    construct_response function?


    I tried:
    :ref:`my_project/api/stuff1:construct_response`

    but that gives an undefined label warning.


    I can answer my own Question 1:
    :func:`construct_response`


    And I can answer my own Question 2: :func:`my_project.main_application.construct_response`

    --- SoupGate-Win32 v1.05
    * Origin: fsxNet Usenet Gateway (21:1/5)