Official web page for uftrace for better accessibility.

[kangtegong]

Currently there is no official webpage for uftrace (except for slide and man pages). It think we can apply readthedocs like below

https://uftrace.readthedocs.io/

or make custom github page for uftrace.

Personally, I think readthedocs is good because it can generate website based on markdowns (or rst files) under doc/ directory.

But if readthedocs invoke lots of changes in uftrace repository or readability is not good enough, custom github page is also fine.

[namhyung]

Sounds good. I'm not familiar with that but current README and manpage should be fine.

@honggyukim what do you think?

[honggyukim]

That will be good. But I hope we can use https://uftrace.github.io instead of https://uftrace.readthedocs.io just like https://docs.kernel.org if possible.

Besides that, I think we better move some documents with good quality to our source repo instead of having them in wiki. For example, https://github.com/namhyung/uftrace/wiki/Data-Format. It's because

1. we don't really update the documents in our wiki.
2. documents can be better synced with source changes.
3. external contributors will likely to contribute as it can be counted in the commit history while wiki update doesn't.

[kangtegong]

I totally agree with @honggyukim :) Thanks.

[yskelg]

We've been planing to add the existing markdown documentation(uftrace.wiki.git, uftrace.git/tree/master/doc) to the uftrace.github.io homepage as sphinx(read the docs, Like the Linux kernel documentation) or mkdocs.

Resources for reference are as follows.

• mkdocs vs sphinx
  • https://pythonbiellagroup.it/en/learning/mkdocs_tutorial/mkdocs_vs_sphinx/
  • https://medium.com/illumination/sphinx-vs-mkdocs-powerful-documentation-using-python-975dd66c9510

	MkDocs	Sphinx
Supported Formats	Markdown	reStructuredText (rST) but with the myst-parser extension supports Markdown
Startup	Easy with the command poetry run mkdocs .	Simple with the command sphinx-quickstart
Configuration	Utilizes a YAML file mkdocs.yml	Utilizes a Python file conf.py
Layout	Elegant and appealing, also navigable	Somewhat dated. The Read the Docs theme is iconic
Build	Provides a local server to fully test the site. Convenient command poetry run mkdocs serve	Generates the site build but the user must then test it in their browser. This is done with make html
Extensions	There are many but not all are maintained	There are many extensions but the community is less active compared to MkDocs
Customization	Infinite possibilities thanks to CSS integration and available themes	Decidedly less customizable
Third-party Integration	Integration with Confluence with this extension	Integration with Confluence with this extension

• Example of mkdocs: aya-rs

  • https://aya-rs.dev/book/
  • https://github.com/aya-rs/book

• sphinx Markdown Tutorial Project

  • https://docs.readthedocs.io/en/stable/intro/getting-started-with-sphinx.html#using-markdown-with-sphinx
  • https://github.com/readthedocs/tutorial-sphinx-markdown
  • https://youtu.be/qRSb299awB0?t=3381

If we using markdown format when drawing diagrams, We can use mermaid supported by markdown as much as possible.

Markdowned mermaid source code interpreted like this.

graph TD
    A[misc/docker/**/Dockerfile] -->|Get Linux distribution Image| B(Linux distribution)
    B --> |Build Essential Package| C[git clone uftrace]
    C --> |Install Dependency| D[Build & unit test]

Mermaid Live Editor

• https://mermaid.live/edit

If you need a table, you can take a table from Excel or a webpage and paste it into Markdown syntax.

• https://tableconvert.com/html-to-markdown

[yskelg]

We can also implement the Read the docs by mkdocs.

• https://github.com/mkdocs/mkdocs/wiki/MkDocs-Themes
• https://github.com/demun/mkdocs-tuts
• https://demun.github.io/mkdocs-tuts/guide/publish/

In my personal opinion, the .md format is more popular than .rst for creating and maintaining websites(Also, We can use mermaid!), and Python is often installed by default on any OS, so I suggest using mkdocs for convenience.

[namhyung]

I don't have any preference.