Move Toga to MkDocs and Markdown #3719
Conversation
|
Read the Docs says that the required |
|
@freakboy3742 @mhsmith The preview is available for you to take a look at. I have outlined the details above, with links to the relevant documentation pages and source code files. I'm happy to answer any questions you may have. |
|
Initial impressions: this looks slick. Even with the TODOs and minor issues, this is looking really good. Three things that stood out on my initial review:
(2) and (3) are somewhat related, because the issues with (2) are more acute on the (3)-style index pages. It's also related to the scrolling issue flagged in beeware/beeware-docs-tools#10 - and made worse by the fact that once there's a header, logo, and footer bar, the amount of real-estate available to display the actual index is fairly constrained. |
core/src/toga/widgets/imageview.py
Outdated
| types defined by installed :doc:`image format plugins | ||
| </reference/plugins/image_formats>`. | ||
| :param format: Format to provide. Defaults to [`Image`][toga.images.Image]; also | ||
| supports [PIL.Image.Image][] if Pillow is installed, as well as any image |
There was a problem hiding this comment.
| supports [PIL.Image.Image][] if Pillow is installed, as well as any image | |
| supports [`PIL.Image.Image`][] if Pillow is installed, as well as any image |
| Every context drawing method creates a ``DrawingObject``, adds it to the context, | ||
| and returns it. Each argument passed to the method becomes a property of the | ||
| ``DrawingObject``, which can be modified as shown in the `Usage`_ section. |
There was a problem hiding this comment.
Not sure about the "usage" reference in this suggestion.
| Every context drawing method creates a ``DrawingObject``, adds it to the context, | |
| and returns it. Each argument passed to the method becomes a property of the | |
| ``DrawingObject``, which can be modified as shown in the `Usage`_ section. | |
| Every context drawing method creates a `DrawingObject`, adds it to the context, | |
| and returns it. Each argument passed to the method becomes a property of the | |
| `DrawingObject`, which can be modified as shown in the [Usage][] section. |
| types defined by installed :doc:`image format plugins | ||
| </reference/plugins/image_formats>` | ||
| :param format: Format to provide. Defaults to [`Image`][toga.images.Image]; also | ||
| supports [PIL.Image.Image][] if Pillow is installed, as well as any image |
There was a problem hiding this comment.
| supports [PIL.Image.Image][] if Pillow is installed, as well as any image | |
| supports [`PIL.Image.Image`][] if Pillow is installed, as well as any image |
This comment was marked as resolved.
This comment was marked as resolved.
This comment was marked as resolved.
This comment was marked as resolved.
|
Thanks for the thorough notes, this looks really good. Just a few comments:
According to the docs, this can also be written as
This also can be done using the
Do you mean the extra space above and below the image? Will this affect all images in the documentation, and why is it necessary?
This doesn't follow the A similar syntax is used for tabs, and it makes the docs source code much longer and much harder to read than the RST equivalent.
mkdocstrings has
It looks like this has now been resolved for the Style page, but not everywhere else, e.g. clicking Resources still takes you to an empty page rather than expanding the sidebar TOC. |
So y'all would prefer relative cross reference if it's possible? Sorry for commenting on a proof-of-concept but on https://mkdocstrings.github.io/insiders/ there's this wording
So if we sponsored them we could publicly use it. I'd like to also bring https://analog-garage.github.io/mkdocstrings-python-xref/latest/ to attention for relative references. It has some nice but weird syntax like (c) for current class and (p) for current package and you can also do like .property or ..attribute like normally. |
kattni
changed the title
|
@freakboy3742 Here's the list that needs docstring content, and the files they are in.
Search for |
I've pushed an update with docstrings for all of these except I've also done a bit of a light re-org of the types around table/tree/selection/detailedList - they were all referencing a locally defined |
|
@freakboy3742: As requested, I've had another look over this, and I'm OK for it to be merged to avoid any more conflicts. |
.readthedocs.yaml
Outdated
| # Docs are always built on Python 3.12. See also the tox config and contribution docs. | ||
| python: "3.12" | ||
| # Docs are always built on Python 3.12. See also the tox config. | ||
| python: "3.13" |
There was a problem hiding this comment.
| python: "3.13" | |
| python: "3.12" |
pyproject.toml
Outdated
| @@ -104,7 +104,35 @@ type = [ | |||
| { directory = "misc", name = "Misc", showcontent = false }, | |||
| ] | |||
|
|
|||
| [tool.setuptools_scm] | |||
| # [tool.setuptools_scm] | |||
There was a problem hiding this comment.
This seems odd - either we don't need setuptools_scm config at the root level, or this has been commented out in error.
4 participants
Progress tracking
There are four major pieces left to this before it becomes individual fixes:
4: Completed
Verify diff and that all links are working properly.
1 and 2: Completed
This is the list of Markdown files in the
docs/en. I am currently going through the Markdown content in each file to verify links and content are accurate, and, when applicable, to verify that class documentation is displaying correctly.Original proof-of-concept content
Original proof-of-concept PR content
This is a proof of concept for switching Toga to Markdown and MkDocs. As requested, I have fully updated a few of the more complex documentation pages and the docstrings for the associated class documentation, and outlined the changes to look for below. Consider this a guided tour of what to expect from MkDocs as a developer and documentation author.
config.ymlThis is the base configuration file that is inherited by the
mkdocs.en.ymlfile. It is separated for consistency, and to enable a straightforward path to translations. I want to quickly explain what is happening in the potentially-less-obvious parts of this file:extra:- Anything in this is made available to the Macros plugin, and can be used as a Jinja variable. The Material theme reads it as well for various things, including, in this case, the social media links that are rendered in the footer. I am using theproject_nameto generate the GitHub URLs in the sidebar. The last four keys are strings that when included in the Markdown as{{ string_content }}, will automatically be replaced by the value paired with the key string.fully_supportedandpartly_supportedin the CSV file is that the tables themselves are rendered by the Jinja run on initial Markdown render, and therefore cannot recognise Jinja directives within the table, as the table content is not available until after the Jinja is expanded.theme:- We are using the MkDocs Material theme. The enabledcontent,toc, andnavigationfeatures are set to create a similar navigation experience to the current documentation. Thesearchfeatures include suggested search term completion, highlighting your search term on the page you navigate to from the search modal, and your search generating an actual URL for sharing purposes.theme: custom_dir- This is the location of the theme overrides, which are provided by BeeWare Docs Tools on build and live-serve of the site.theme: palette- This provides light mode, dark mode, and automatic mode which follows the system preference, including automatically changing depending on the time of day without needing to refresh the site.markdown_extensions:- PyMdown Extensions (pymdownx) is a collection of extensions for Python Markdown. We are using several of them. Anything not beginning withpymdownxis standalone. Most extensions are pretty self-explanatory. Less obvious are:pymdownx:caret- This provides the ability to use^to superscript text. It is used for the beta and no-support symbols, but can be used for anything.snippets- This provides the syntax for including external content, either from a local file or from a URL. I have noted two files below that show the syntax in action for including a local file. Snippets has the option to provide delimiters in a file, and syntax to limit the content included to what is contained between the delimiters. It also allows you to include specific line numbers or a range of line numbers; however, I don't recommend it as, if the file changes, you will have to remember to update your include content. The delimiters are a convenient way to avoid that problem.base_pathis a provided directory that the include path can begin with. In the event that you wish to include content from another directory, you would add it here.attr_list- This provides syntax for custom anchors on headers and text. The header format is{ id="anchor-name" }, included after the header with a space between the end of the header and the opening curly bracket. This can be done on any header to provide any custom name. The arbitrary text anchor format is[](){ id="anchor_name" }on a blank line above the intended paragraph, with whitespace before and after. This means if you link to that anchor, it will navigate to that paragraph of text.plugins:- Most of these are also self-explanatory. Worth noting are:autorefs- This is the plugin that handles the class documentation linking, and the direct anchor linking. As there are several iterations of the link syntax; they are all exhibited in the documentation updates. The basics of linking class documentation is[displayed text][class.Module], or if you wish to link to the full class name, [class.Module][]. The basics of anchor linking is[displayed text][anchor-name]or if you wish to display the anchor name,[anchor-name][]. There are more details and examples below.literate-nav- I tried several options for controlling how the left sidebar navigation is displayed, and this was the only option that allowed me to replicate the current documentation layout. It requires explicitly writing out the link layout in theSUMMARY.mdfile that lives with the documentation. Once this file is present, if an intended sidebar link is not included in the file, it will not be displayed. If a file or directory exists that will be excluded due to this file, the build and live-serve will fail on a warning. There is work required initially to get this set up, but it's relatively straightforward to keep it updated. Not everything needs to be included, only link structures that you want to specify, or links that have display names that don't match the filename or directory name. Otherwise, links are alphabetical. If you view the linked file, you'll see what was required for Toga to look similar to how it looks currently.macros- This provides a lot of Jinja options including automatic replacement of key:value pairs from theextrakeyword above, and basic Jinja including conditionals and loops. It's necessary for the CSV tables generated bytable_reader, and provides options for a lot of other things.table-reader- This generates the tables from the CSV file for the widgets. It uses themacrosplugin, and Pandas. Syntax is identified below.mkdocstrings-mkdocstringsis the MkDocssphinx-autodocequivalent. It generates the class documentation from the source code. Configuration details are below.Documentation features by page
docs/en/index.md)caption. Note the extra whitespace; it is necessary for it to render properly.index.mdfile, you do not need to include/index.mdon the end of the link target.docs/en/reference/api/resources/images.mdand (images.py){{ pd_read_csv).Keyin theAvailabilitytable title shows the syntax for linking text to an existing anchor. This can be either a custom anchor you provided, or the anchor that is automatically generated by Markdown (e.g. the anchor for this page would beimage).:class:~module.Classlinks. So:class:~toga.Imagewould be [Image][toga.Image]. You must supply the backticks for it to be rendered as inline code.[text][module.Class]. In this case, it links the text toImageContentT, with[wide range of sources][toga.images.ImageContentT].[](){ id="known-image-formats" }. SeeImageContentTfor an example of linking to these anchors.ImageContentTis displayed in the reference documentation, and is linked both manually in links, and automatically in the TYPE: element. The docstring is pulled from the originalimages.rstfile, where the info is currently displayed.ImageContentTis in the code, it doesn't see the= PathLikeT | BytesLikeT | ImageLikeTas a "signature", and therefore doesn't allow for hiding it. This would likely be the case with any linked typealias. There are potential workarounds I'm sure; however, I did not begin looking into this yet.as_formatfor a link toPIL.Image.Image. The syntax is [PIL.Image.Image][].docs/en/reference/api/widgets/imageview.mdandimageview.py)module.Class][]. So,:class:toga.Buttonwould be [toga.Button][]. Backticks required for inline code rendering.ImageContentTis displayed in the reference documentation, and is linked both manually in links, and automatically in the TYPE: element.separate_signatureandshow_signatureoptions are disabled on the class documentation, to show what it looks like without them.toga.ImageViewin code format, or it is a text header "toga.ImageView" with a codeblock below it including eitherImageView, ifshow_signatureis disabled, orImageView(image=None, id=None, style=None, **kwargs), ifshow_signatureis enabled.imagefor an example of linking toNonein the Python docs. The syntax is [None][].docs/en/reference/api/widgets/canvas.mdand/canvas/*.py)autorefequivalent of:meth:~Canvas.redraw, which is [Canvas.redraw][toga.Canvas.redraw]. Backticks required for inline code rendering.toga.Canvasmkdocstringscall shows what is necessary to include specific class members. To look at it another way, to exclude specific class members, you must list the members you want to include.:yields:is not currently supported bymkdocstrings(a feature request is in and has been acknowledged). The workaround is to use:return:and specific wording to the effect of "Yields the new...."DrawingObjectfor two examples of the:meth:equivalent. To render:meth:~toga.widgets.canvas.Context.appendis [append()][toga.widgets.canvas.Context.append].docs/en/reference/widgets_by_platform.mdandwidgets_by_platform.csv)docs/en/reference/api/mainwindow.md)docs/en/reference/api/widgets/tree.md)-8<- "reference/api/widgets/table-accessors.md". The-8<-is either on the same line as the file, or if you want to include multiple files, you can put it on a line of its own, the files below it, each on their own line, and another instance of-8<-below that. Including a file from a URL is the same syntax; simply replace the filename with the URL.mkdocstringsThe available configuration options can be found here. There are many. They are separated into five categories: General, Headings, Members, Docstrings, and Signatures. I recommend reviewing them all, as there may be things available here that you feel are better than what the current documentation had to offer, which is why I am including the link here; they provide a good explanation of what each option does and show examples for many of them.
I have enabled several based on the current documentation, which I have outlined below. They are separated into sections based on whether they are required, highly recommended, or you need to take a look at the link above and the rendered documentation as linked below and make a decision on how you want it to look.
Currently set
mkdocstringsconfiguration options:Required:
docstring_style: sphinx- Parses docstrings from Sphinx formatting; the:parametc. formatting, not parsing rST links.show_root_heading: true- Shows the class name and/or signature, based on other options. This is absolutely necessary, otherwise no info on the class name is rendered.Highly recommended as-is:
docstring_section_style: spacy- The layout of the docstring information. The other options aretableandlist. Thespacyoption looks the best to me; it shows the info with the least amount of superfluous information or whitespace. Recommend keeping this as-is.merge_init_into_class: true- If disabled,initis displayed separately. Highly recommend this setting.show_source: false- Enabled by default; shows the source code for the class below the signature if enabled; I don't recommend enabling it; it is entirely too busy.Your opinion needed:
members_order: alphabetical- Shows class members alphabetically; the other option issourcewhich is ordered based on the source code.allow_inspection: false- True includes dunder methods; this can be enabled on individual class entries if you want them included.annotations_path: brief- Determines the verbosity of the annotations path. This is the recommended setting. Other options aresourceandfull.show_labels:which defaults totrue. This is what handles the member labels likeinstance-attributeandpropertywritable. I wanted to point out that this is configurable, though I didn't include it in the current configuration.Signature settings - your opinion needed:
Context: the "signature" is the code-rendered display of a class/method/attribute/function name. It can be shown below a text-rendered version of the name, or it can be the only version of the name displayed. This is entirely a personal preference option.
separate_signature: true- Shows theClassName(args)separately from header name. There are examples of it enabled and disabled in this PR.show_signature: true- Displays()or(args)along with the function name in the signature. This should for sure be disabled if you choose to globally disable theseparate_signatureoption.show_signature_annotations: false- Disabling this removes annotations from the signature. Highly recommend this setting regardless of whether you opt for a separately displayed signature; enabled it's too much.line_length: 80- Forces longer signatures to be stacked, instead of overflowing their space and triggering a scrollbar. Requires Black. If you opt to hide signatures, this can be removed, though I would consider leaving it in to handle signatures if they are enabled on individual class calls.Included only for the visual:
show_symbol_type_toc: true- Adds the colorful symbols next to the function/class names in the sidebar table of contents. This is what they added on place of renderingfunction()(with parens) in the sidebar list. I have a feature request in for making it configurable to include the parens, but there hasn't been any movement on it. It seems like a lot to me, and also doesn't mean much to me in terms of whether it adds any meaningful information based on my level of knowledge. I enabled it so you could see it, but I am not sure if it's worth keeping.Linting
There are two tools being used for linting, beyond what MkDocs, Macros, and
autorefsare doing automatically on build.markdown-checkeris being used to verify external URLs are still valid.pyspellingis the spellchecker.pyspellingfor the purposes of this demonstration, as this is meant only to be a proof of concept.Potential blockers and nice-to-haves identified before starting this process
There were a few potential blockers identified ahead of this process. I want to document them and the solutions here.
sphinx.autodoc?mkdocstrings. I linked to the configuration options above.autorefs, and the syntax for various types of links are outlined above.literate-navplugin, as outlined above.beeware-docs-tools, and the existing translations have been successfully migrated.There were a few nice-to-haves as well that are possible with MkDocs.
Noteable CSS issues:
Miscellaneous:
TODOs in various places, including comments in the Markdown to update the alt text on images. This is something I think should be done, as the alt text provided in the existing documentation is the path to the file. They are specifically HTML tagged comments so they will not render in the Markdown, and therefore can be dealt with at any time in the future. It may be worth a future good first issue.pyproject.tomlto dependency groups. This meant moving the dependencies to thepyproject.tomlin the root of the project, fortoxto be able to use them.core/pyproject.tomlintact, because I don't entirely understand how Toga works in this regard, and I didn't want to break something else. I imagine the dependencies should be removed fromcore/pyproject.toml, but I will wait on that until it is clarified.TODO:
Among other things, the following changes are necessary before finalising:
TODOs in docs and code, and resolve necessary tasks.--build-with-errorsfromtox.ini:docsliveanden.pyspellingintox.iniand resolve errors.rumdltopre-commit, resolve errors. - Tool is not ready at this time to be added topre-commit.PR Checklist: