Separate .slint language, element and widget documentation into a separate doc site

[tronical]

Discussed in https://github.com/sixtyfpsui/sixtyfps/discussions/762

We want to move the .slint related documentation out of the C++ and Rust API Documentation and into a site of its own, created using sphinx, myst-parser and maybe rtd-theme. This site can offer search, references to C++/Rust and more.

For the overall documentation we'd like to then have a Documentation landing page that refers to the Rust API, C++ API and .slint reference docs as sub-sites.

[Be-ing]

mdbook is another option

[darkwyrm]

I'm considering working on this issue and would like to use mdbook if I move forward as it is close to the Rust ecosystem and there is already documentation in the tree that uses it. What are the expectations / desires for the new site?

[tronical]

Hey. That’s awesome :). I’m a bit unsure about mdbook for reference documentation, but that doesn’t mean it can’t work.

One motivation is the ability to search well through the reference, and the other is the ability to link from rust/c++ to the Slint reference and back. It’s probably fine to use html links, if they are stable.

What do others think?

[Be-ing]

We're using mdbook for CXX-Qt which you can see here. mdbook's search feature works well. I think it would be more appropriate for the .slint language and element documentation than rustdoc. rustdoc is specifically meant for Rust code; its search functionality only searches for Rust symbol names. By contrast, mdbook searches the whole text. Another nice feature of mdbook is that you can include code with syntax highlighting from other files, so you can use code from examples and tests directly in the documentation without having to maintain the code inline in the documentation.

[ogoffart]

I think what we need is:

• A getting started guide
• Some more explanation about how things work
• The reference of all different elements and their properties. (this is important that this should be searchable)

Each of these are quite different, but should still be well integrated.

(See also https://documentation.divio.com/ )

Also, we aim to integrate with different programming language, and we would like that for each language, they have a good documentation, and that it wouldn't need to know (or see?) rust for a C++ programmer.

For example, we use sphinx https://slint-ui.com/docs/cpp/ and this provide both the reference and some pages. In the rust ecosystem, docs.rs is used to generate the reference documentation, but the non-reference documentation is often using mdbook.

So we need a way to have documentation and reference for each programming language, and for the .slint language.

Currently, we duplicated the .slint documentation for each language, so we have both https://docs.rs/slint/latest/slint/docs/builtin_elements/index.html and https://slint-ui.com/releases/0.3.1/docs/cpp/markdown/builtin_elements.html with the same contents. (and the JS documetation is fairly bad at the moment) And none of this is properly searchable. (How do I access the documentation of ComboBox easily? the Sphynx docs are a bit better than rustdoc here, but still not ideal)

One question is if we should move to have only one Slint language reference and documentation site instead of duplicating it.

Now, is mdbooks a good choice for the .slint reference (if we want to have proper search)?

[ogoffart]

Preview of the work in progress for the separate .slint docs in https://slint-ui.com/snapshots/master/docs/slint/

[Be-ing]

That is much nicer to navigate. :+1:

[tronical]

Olivier, Tobias, and I discussed this a little further. We started out separating the language reference into its own mdbook, and now we'd like to try creating one single site instead with sphinx. A single site that's searchable and can include the c++ reference seems attractive to us.

We started out with a clean-room structure:

Structure

1. Introduction (this teaches what the slint language is, how to write)
2. Concepts
  - files, components and elements
  - positioning and layouts
  - native code
    - integrating with rust
    - integrating with c++
    - integrating with nodejs
  - Slint on Microcontrollers
1. Language Reference
 - types
 - components
 - functions
 - expressions
1. Builtins Reference
 - enums
 - elements
 - widgets
1. Native reference
 - cpp | cpp is a link
 - rust is a link
 - node is link
1. how to use the design tool

Options

We discussed four options, where option number zero is the current setup:

0. Multiple sites, with slint reference duplicted (current)

Each language integration has its own standalone docs we repeat slint docs everywhere

1. Multiple Sites:

  Slint Book: slint-ui.com/docs/slint
     - Language concepts
     - Language reference
  Cpp Book:  slint-ui.com/docs/cpp
     - Cpp concepts
     - Cpp tutorial
     - Cpp Reference
  Rust Book: slint-ui.com/docs/rust
     - Rust Concepts
     - rust Tutorial
     - link to rustdoc reference
  Rust Doc reference
  Node Book (Reference + concepts)
  Design tool book

2. One Site

  Slint Book:
    - Intro
    - Concepts
      - Native (can link to native reference below)
         - split with link to the relevant language
         cpp
         rust
          - Slint stuff (layouts, etc.)
    - Tutorials
       - cpp
       - rust
    - Language Reference
    - Builtins Reference
    - Native API reference 
       - Cpp Reference
       - Link to Rust reference
       - ....

3. One Site v2

 Slint Book: 
    - Intro
    - Concepts
       - links to the different concepts pages
    - Slint Language
      - Concepts
      - Reference
    - Native API
      - General concepts (small)
      - Slint C++
        - Concepts
        - Tutorial
        - Reference
      - Slint Rust  
        - Concepts
        - Tutorial
        - Link to rustdoc

[Be-ing]

Any of those look like they could work okay, so long as rustdoc isn't abused for content beyond documenting the Rust API. :)

[hunger]

@Be-ing: Reducing the rustdoc docs to API only is part of why we do this. Another reason is to to have better docs in general :-)

[aurindam]

Probably too late too suggest -- I came across https://github.com/markdoc/markdoc which Stripe uses

[tronical]

I remember when mark doc was announced and I was tempted, but it's only a developer api basically. We would still have to write the "documentation tooling" around it.

[tronical]

We have now a new landing page at https://slint-ui.com/snapshots/master/docs/ and the Slint language docs all combined into one book at https://slint-ui.com/snapshots/master/docs/slint/index.html . In addition we proof-read it and made many small improvements. I think that we can close this task for now.