Searching sixtyfps documentation through rustdoc

[Vollbrecht]

My default behavior as a new user to sixtyfps is to search through the rustdoc. If i want to find for example information about "VerticalLayout" the search result will be empty. (As a new user i find it irritating that i cant search keywords like that releated to the .60 documenation)

I understand that this is a limitation of rustdoc, because the documentation is essentially loaded as an md file and can not be indexed when the documentation is compiled.

Should there be a hint for other new users that the search function does not provide results for .60 documentation ?

Since i am not able to search through rustdoc my current workflow for searching boils down to the following:

• use a searchengine to find it
• memorize where to find all elements in the documentation and navigate manual through the docs folder
• use IDE TextSearch

Using an searchengine the top result often is not the current version of the documentation and the search is more susceptible to random noise i am not looking for.

Manually navigation through the docs folder is possible, but as the documentation grows it will be more and more less feasible and slow.

Using TextSearch (e.g. VScode CTRL + SHIFT + F )is a possibility and with a better editor configuration on my part could work but destroys the "out of box" experience.

So my question to you:

• How do you use the sixtyfps documentation ?
• Is there something fundamental i am missing? :D
• Should there be a separate documentation(e.g readthedocs ) provider for the .60 part because its not integrated in rustdoc ?

[tronical]

That’s a very good set of questions! You’re not missing anything fundamental. I usually have a tab with the markdown files open, but I’d love a better searchable and better integrated experience.

A separate site makes a fair bit of sense actually. I wonder what a good format and doc tool would be that would still allow the integration like we currently have, in parallel?

[ogoffart]

We could also try to generate fake structs or functions for each elements so it become an actual item for rustdoc.
But i guess trying to integrate everything in rustdoc is maybe not the best and we should create a separate book instead.

[Vollbrecht]

tldr:

i created this simple example to showcase one simple fast solution:
https://vollbrecht.github.io/

.md as documentation workflow ?

i think a simple text based solution like md files for documentation is still a nice thing to have because it is very accessible. so if you want to stay with it, i propose a relative simple solution to this.

my "requirements" for a solution

• stay with md files for docu
• create an indexed searchable site for easy searching
• possible different outputs -> html , pdf ..etc
• fast to setup / easy to update
• versioning

My solution:

Use sphinx with the myst-parser extension to enable md file parsing. sphinx is a documentation generator or a tool that translates a set of plain text source files into various output formats. The output of sphinx than can get used locally, get pushed to an documentation provider like in the example on github.io or something more sophisticated with build and version-control for docu like readthedocs or simply get pushed on an docs.sixtyfps.io webroot or similar.

HowTo:

Prerequest for locally building the docu:

• python

Onetime tasks:

• setup sphinx (Time: 30 sec)
  • python -m pip install -U sphinx
  • (alternative) https://www.sphinx-doc.org/en/master/usage/installation.html
• create docu/source and docu/build dir in sixtyfps repository and copy all md files that should be included in the source dir
• in ../docu/ dir run sphinx-quickstart and setup default information about project name, author etc (Time: 1 min)
• enable myst-parser for md files (Time: 10 sec)
  • open docu/conf.py and add "myst_parser" to extension = []
  • extension = ["myst_parser"]
• edit the index.rst file and add all .md files to it so it look like this: (Time: 30 sec)

Welcome to sixtyfpsui's documentation!
======================================

.. toctree::
   :maxdepth: 2
   :caption: Contents:

.. toctree::
   building.md
   builtin_elements.md
   debugging_techniques.md
   development.md
   install_qt.md
   langref.md
   layouting.md
   testing.md
   widgets.md

• for a more sophisticated setup tweak the .rst file to your liking (Time: inf :) )

• optional github.io:

  • to publish to github.io create an empty repository with the name sixtyfps.github.io

  • git clone https://github.com/sixtyfps/sixyfps.github.io

  • we dont want github to alter our page so we need .nojekyll file.

    • touch .nojekyll in cloned repository

repeatable task on md changes:

• for every new .md file add it to the .rst file (relativ path to source possible)

• sphinx-build -b html sourcedir/ builddir/ or just make html

• navigate to sourcedir and open index.html and enjoy the docu locally in the browser

• optional github.io:

  • copy build for publishing
    • cp -r ../path/to/builddir/* ../path/to/sixtyfps.github.io.dir/
  • git add --all
  • git commit -m "commit msg"
  • git push -u origin main
  • visit https://sixtyfps.github.io

• PROFIT

Whats next ?

This is now a super bare bone version( still much more useful than the current state :) ) but working. So one could start tweaking the rst file (sphinx-getting-started) or just stay in the .md domain and leverage the power of the myst-parser.

We now have an relative straightforward solution but missing a good way of versioning. This is not a problem for the build in each version of the repo but rather a problem if we just bare bone host the generated html like in the github.io example. Like in all steps there are several different possibility to get it done. One way is using https://docs.readthedocs.io/en/stable/tutorial/. With some small modifications to the docu git structure we can build an more automated process like trigger docu builds from pull request etc and receive an versioned docu similar to the rustdoc.

What do you think ?

[ogoffart]

I think that's great to pay some love to the documentation.
Not all that is in the docs folder is meant to be for users of sixtyfps (eg, the development guide)
In the long term we also wanted to auto-generate the documentation for the widgets from comments in the .60 files. But that's out of scope for this.

We already use sphinx for the C++ docs here: https://sixtyfps.io/snapshots/master/docs/cpp/

What we probably should have is a "book" that is independent of the language, instead of repeating the .60 language reference on every documentaiton.

[tronical]

To build on what @ogoffart said, we discussed this a bit more and agree about this direction. I have had a very positive experience using myst-parser, I think that we should stay with markdown.

We were thinking of a doc landing page that offers further access to the Rust API reference, the C++ API reference as well as the documentation for the .60 language and built-in elements. The latter would then be built using the technologies you mention, sphinx, myst-parser and maybe the same RTD theme as the C++ docs.

The individual API docs would not include a "copy" of the .60 docs anymore but instead link to the new site. And vice versa, the .60 docs can refer to the reference using relative links ("Check out the Rust API docs and the C++ docs for how to access the global singletons from your programming environment").

I've filed #793 .