Page MenuHome

API docs: intro overhaul
ClosedPublic

Authored by Tobias Heinke (TobiasH) on Thu, Jun 18, 10:58 PM.

Details

Summary

wording, spelling, formatting,...
screen to workspace
update 2.8 UI changes
py 2 '%' to 3 format function: tested all as snippets, linted files

Not Done:

other code updates
space vs. editor
User Preference to Preference
editor caps
menuselection: needs CSS fixes

Diff Detail

Repository
rB Blender

Event Timeline

Tobias Heinke (TobiasH) requested review of this revision.Thu, Jun 18, 10:58 PM
Tobias Heinke (TobiasH) created this revision.

Documentation changes seem like they're fine (only checked basics, will commit these in parts).

Note that I won't apply these Python changes as part of a documentation patch,

When checking this I found some mistakes, and I don't think it's much of an improvement, also replacing %s with {0} means we loose the type information, would prefer {:s} in this case.
Although I don't think this is an especially important change to make - for the review and testing that's required.

doc/python_api/sphinx_doc_gen.py
2106

Gives the error: ValueError: Sign not allowed in string format specifier

doc/python_api/sphinx_doc_update.py
181

Looses symlink's second argument.

196

Looses symlink's second argument.

doc/python_api/sphinx_doc_gen.py
1723

This could be a functional change, better not mix these in with cleanups.

When checking this I found some mistakes, and I don't think it's much of an improvement, also replacing %s with {0} means we loose the type information, would prefer {:s} in this case.

If we are going to move to a newer style of string formatting, I would prefer f-strings rather than str.format() calls.

Something like this:

"rsync://%s@%s:%s" % (args.user, args.rsync_server, args.rsync_root)

would then become:

f"rsync://{args.user}@{args.rsync_server}:{args.rsync_root}"

@Sybren A. Stüvel (sybren) not sure on moving to f-strings, I like the idea of them but I'm not sure they work as well in editors, auto-completion, autopep8, syntax-highlighting error checking... etc.

In the rsync example it seems OK, but adding more logic into them (function calls, operators... etc) I'd prefer not to use them.

Thanks, Devs who started with py3 don't know the old.
But should then include the py-file examples.
If I should do this let me know, but since I didn't notice this mistakes...

doc/python_api/rst/info_best_practice.rst
369

You committed this (just in case)

doc/python_api/sphinx_doc_gen.py
362

here's a tiny text edit

@Sybren A. Stüvel (sybren) not sure on moving to f-strings, I like the idea of them but I'm not sure they work as well in editors, auto-completion, autopep8, syntax-highlighting error checking... etc.

Editors work pretty well with them. They are not brand-spanking new, they're 3½ years old and were introduced two versions of Python ago.

In the rsync example it seems OK, but adding more logic into them (function calls, operators... etc) I'd prefer not to use them.

IMO that's beside the exact formatting method used. Calls to str.format() or % formatting shouldn't have much logic in them either, just to keep the code simple & readable.

Personally I don't see the point of going through the effort of replacing the % formatting. The syntax is fine, it's not like the formatting method is being deprecated any time soon. If we want to modernise, IMO it makes more sense to use f-strings. This is not something to discuss in this patch, however, so I'll start a discussion on devtalk about this.

I agree that the string formating is not a huge deal, I don't think it should be part of this patch but should be re-evaluated for our code style guidelines in a different discussion.

doc/python_api/sphinx_doc_gen.py
1723

This is not functional, the function was renamed in newer sphinx versions. add_stylesheet is deprecated. The change is okay with me.

Committed the things @Tobias Heinke (TobiasH) brought up in rBb0449cac6629b6f3f86ecacabdebc7e24ad51c37 all that's remaining in the patch are the string changes which if they should happen need to be established on a larger scale first. Closing the patch, all functional changes have been made.

This revision is now accepted and ready to land.Tue, Jun 23, 11:15 PM