Message-ID:

Innovation distinguishes between a leader and a follower. -- Steve Jobs (1955-2011)

devel / comp.lang.python / Generating documentation with Sphinx

Generating documentation with Sphinx

<mailman.253.1693248393.23016.python-list@python.org>

https://www.novabbs.com/devel/article-flat.php?id=23925&group=comp.lang.python#23925

copy link Newsgroups: comp.lang.python

Path: i2pn2.org!i2pn.org!weretis.net!feeder8.news.weretis.net!fu-berlin.de!uni-berlin.de!not-for-mail
From: jsf80...@gmail.com (Jason Friedman)
Newsgroups: comp.lang.python
Subject: Generating documentation with Sphinx
Date: Mon, 28 Aug 2023 12:46:20 -0600
Lines: 52
Message-ID: <mailman.253.1693248393.23016.python-list@python.org>
References: <CANy1k1hh+z61DtrYUfZbtsYRdXTZmJ=hLqprfbd-mrEjM=NtNA@mail.gmail.com>
Mime-Version: 1.0
Content-Type: text/plain; charset="UTF-8"
Cancel-Lock: sha1:CMc7bggsxdwDR+SR8mB3uTMyW9U= sha256:FpaS8IY4p1VyraT2JehvO8/U0q80+sN3LvY1osELC8M=
reason="2048-bit key; unprotected key"
header.d=gmail.com header.i=@gmail.com header.b=KrYXTWwN;
dkim-adsp=pass; dkim-atps=neutral
X-Spam-Status: OK 0.002
X-Spam-Evidence: '*H*': 1.00; '*S*': 0.00; 'generated': 0.03;
'message:': 0.03; 'def': 0.04; 'received:mail-
ed1-x52b.google.com': 0.07; '"""': 0.09; 'construct': 0.09;
'page:': 0.09; 'url:stable': 0.09; '->': 0.16; 'endpoint':
0.16; 'structure:': 0.16; 'api': 0.17; 'to:addr:python-list':
0.20; 'stuff': 0.25; 'questions,': 0.26; 'flask': 0.26; 'else':
0.27; 'function': 0.27; 'example,': 0.28; 'question': 0.32;
'(this': 0.32; 'message-id:@mail.gmail.com': 0.32; 'but': 0.32;
'received:google.com': 0.34; 'subject:skip:d 10': 0.35; 'url-
ip:104.17/16': 0.35; 'from:addr:gmail.com': 0.35; 'two': 0.39;
'rest': 0.39; 'something': 0.40; 'in,': 0.60; 'gives': 0.62;
'advertising': 0.64; '200': 0.65; '500': 0.70
DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed;
d=gmail.com; s=20221208; t=1693248391; x=1693853191;
h=to:subject:message-id:date:from:mime-version:from:to:cc:subject
:date:message-id:reply-to;
bh=rblAUdMeYfnoj6eipsPc/eyJmW44Sqk27e0fop8hxs4=;
b=KrYXTWwNGN2Pt4wSlaiQCfFOiQ/7MLj2BL/+lnsdaiK7QFaM/Mfn4SYq0hmrmGdL4d
GQUv4RPcarU6RWT+0GfMOQ8Iu0VaquCxH/sJ0kutL1FlDmmdXwFVeZTMaDTENrZfph2G
GULM3rtf0WUGFLZQeYMbpK2rHjvy/8drTJBn8p4+euaE1HKR/8SorE1TuYqZVAMz/LvZ
Oso91xqlZHQT1OZ6DNmrOJ7s90o/pU1zWe5DAzUxhrG26M/xMKW6Ui2b0l65FTbiMGOp
J8nUkVm8pykP4ZcKRlCZ+aHxnkNJwI5rTRadm+R7RDGSjwYWh07fRIudhGFfglyVOMT8
rkIw==
X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed;
d=1e100.net; s=20221208; t=1693248391; x=1693853191;
h=to:subject:message-id:date:from:mime-version:x-gm-message-state
:from:to:cc:subject:date:message-id:reply-to;
bh=rblAUdMeYfnoj6eipsPc/eyJmW44Sqk27e0fop8hxs4=;
b=dKAS9ei3Ctf1xKNe+VuS9Vh0BnPDVe05e2av/KPQtAZGCeNGSGSR61V0L6eSPJhAbq
nW8dV7g83wJ0KXfqev5E+rRnPLt29TPfpMWuZVV7WTOD3ncZXOK0XIdJdA+YNNKreNP9
mI0GFPsiOczrHENosdHeA11yODbJn45nn2KLMOzLC8Df1r6rTehzegWx/s5HFpBHHF43
rhIHngHLrVfoRhaaE0yJrSq3Pcn0WU6N1FDAq0TDYA8jv/g/BksyE0+AK4sYbN9Bu9FV
9BtwzPqhAjeMupkgoVVGHbD9NfR2zV3tuDKIBs+X04XshYPouyUMnwuKl4zCtp8LFlPi
5Mhg==
X-Gm-Message-State: AOJu0YyOa/MfhVkCDuCYbdl5Y20/OI7utTP2hVWitjvmYId3F6z2qDCs
/yWLxgYb2lD04BEcuSchHBgeMSoQdQyJNmnpc1yAPCs3rkg=
X-Google-Smtp-Source: AGHT+IGVkzEUB2RmA93/xeED2j6RmMenTU0nAE/S77qpFrUsp4nrJMUVwIhY17i+CcM2uRcUuoEfu0UmybyRNdyq4ss=
X-Received: by 2002:a17:906:10a:b0:9a5:a44a:86f3 with SMTP id
10-20020a170906010a00b009a5a44a86f3mr3460770eje.25.1693248391370; Mon, 28 Aug
2023 11:46:31 -0700 (PDT)
X-Content-Filtered-By: Mailman/MimeDel 2.1.39
X-BeenThere: python-list@python.org
X-Mailman-Version: 2.1.39
Precedence: list
List-Id: General discussion list for the Python programming language
<python-list.python.org>
List-Unsubscribe: <https://mail.python.org/mailman/options/python-list>,
<mailto:python-list-request@python.org?subject=unsubscribe>
List-Archive: <https://mail.python.org/pipermail/python-list/>
List-Post: <mailto:python-list@python.org>
List-Help: <mailto:python-list-request@python.org?subject=help>
List-Subscribe: <https://mail.python.org/mailman/listinfo/python-list>,
<mailto:python-list-request@python.org?subject=subscribe>
X-Mailman-Original-Message-ID: <CANy1k1hh+z61DtrYUfZbtsYRdXTZmJ=hLqprfbd-mrEjM=NtNA@mail.gmail.com>

by: Jason Friedman - Mon, 28 Aug 2023 18:46 UTC

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.

Subject	Author
Generating documentation with Sphinx	Jason Friedman