Summary

Make use of data set by @webapi_docs.

Review Request #14045 — Created July 17, 2024 and submitted April 30, 2025, 9:40 a.m.

Information

Owner

david

Repository

Review Board

Branch

master

Bugs

Depends On

Reviewers

Groups

reviewboard

People

Description

This change updates our docs builder to prefer documentation included by
the new @webapi_docs decorator instead of relying purely on docstrings.

Testing Done

Migrated some API documentation out of docstrings into @webapi_docs and
built the user manual. Checked that the API documentation was correct.

Commits

Summary	ID
Make use of data set by @webapi_docs. This change updates our docs builder to prefer documentation included by the new @webapi_docs decorator instead of relying purely on docstrings. Testing Done: Migrated some API documentation out of docstrings into @webapi_docs and built the user manual. Checked that the API documentation was correct.	fe18b256ff4e74f5052d28a61f9cd2d374a6918a

Issues

Description	From	Last Updated
module level import not at top of file Column: 1 Error code: E402	reviewbot	July 17, 2024, 2:33 p.m.
Maybe better to assert docs is None or isinstance(docs, str) to avoid the assumption and keep the type safety.	chipx86	March 17, 2025, 8:40 a.m.
'typing.Optional' imported but unused Column: 1 Error code: F401	reviewbot	March 17, 2025, 8:42 a.m.
'typing.cast' imported but unused Column: 1 Error code: F401	reviewbot	March 17, 2025, 8:42 a.m.
module level import not at top of file Column: 1 Error code: E402	reviewbot	March 17, 2025, 8:42 a.m.
module level import not at top of file Column: 1 Error code: E402	reviewbot	March 17, 2025, 8:42 a.m.

flake8 failed.

JSHint passed.

flake8

docs/manual/_ext/webapidocs.py (Diff revision 1)
The issue has been dropped. Show all issues
```
module level import not at top of file

Column: 1
Error code: E402
```

Ship it!

```
Ship It!
```

docs/manual/_ext/webapidocs.py (Diff revision 1)

The issue has been resolved. Show all issues

Maybe better to assert docs is None or isinstance(docs, str) to avoid the assumption and keep the type safety.

Commits:

	Summary	ID
	Make use of data set by @webapi_docs. This change updates our docs builder to prefer documentation included by the new @webapi_docs decorator instead of relying purely on docstrings. Testing Done: Migrated some API documentation out of docstrings into @webapi_docs and built the user manual. Checked that the API documentation was correct.	0586ba353239e1c80843ec74ccd55bcc707923f6
	Make use of data set by @webapi_docs. This change updates our docs builder to prefer documentation included by the new @webapi_docs decorator instead of relying purely on docstrings. Testing Done: Migrated some API documentation out of docstrings into @webapi_docs and built the user manual. Checked that the API documentation was correct.	33f79e2f066d0becbe4153ed12a6a38db162c61a

Diff:

Revision 2 (+74 -8)

Show changes

docs/manual/_ext/webapidocs.py

Checks run (1 failed, 1 succeeded)

flake8 failed.

JSHint passed.

flake8

docs/manual/_ext/webapidocs.py (Diff revision 2)
The issue has been dropped. Show all issues
```
'typing.Optional' imported but unused

Column: 1
Error code: F401
```
docs/manual/_ext/webapidocs.py (Diff revision 2)
The issue has been dropped. Show all issues
```
'typing.cast' imported but unused

Column: 1
Error code: F401
```
docs/manual/_ext/webapidocs.py (Diff revision 2)
The issue has been dropped. Show all issues
```
module level import not at top of file

Column: 1
Error code: E402
```

Commits:

	Summary	ID
	Make use of data set by @webapi_docs. This change updates our docs builder to prefer documentation included by the new @webapi_docs decorator instead of relying purely on docstrings. Testing Done: Migrated some API documentation out of docstrings into @webapi_docs and built the user manual. Checked that the API documentation was correct.	33f79e2f066d0becbe4153ed12a6a38db162c61a
	Make use of data set by @webapi_docs. This change updates our docs builder to prefer documentation included by the new @webapi_docs decorator instead of relying purely on docstrings. Testing Done: Migrated some API documentation out of docstrings into @webapi_docs and built the user manual. Checked that the API documentation was correct.	fe18b256ff4e74f5052d28a61f9cd2d374a6918a

Diff:

Revision 3 (+74 -8)

Show changes

docs/manual/_ext/webapidocs.py

Checks run (1 failed, 1 succeeded)

flake8 failed.

JSHint passed.

flake8

docs/manual/_ext/webapidocs.py (Diff revision 3)
The issue has been dropped. Show all issues
```
module level import not at top of file

Column: 1
Error code: E402
```

Ship it!

```
Ship It!
```

Status:: Completed
Change Summary:: Pushed to master (432051b)