Revisit documentation platform for better UI

[kenji-miyake]

Now Autoware.Auto uses Doxygen, but it has some disadvantages:

• UI is not modern.
• Search is slow.
• Some special syntaxes that developers aren't used to are required.
• etc.

Therefore, we'll propose a new documentation platform to use mkdocs-material
The advantages are:

• UI is beautiful.
• Search experience is great.
• Pure Markdown can be used.
• Multiple versions of the documentation are supported.
• etc.

Actually, we've already introduced this in autoware.universe as a trial.

[kenji-miyake]

We'll set up mkdocs-material for this repository as well and try to prepare the equivalent documents as Autoware.Auto.

[xmfcx]

Why not https://readthedocs.org/ ? (I've never heard of mkdocs before)

(ROS2 uses it and it is also fast and beautiful https://docs.ros.org/en/rolling/index.html )

[kenji-miyake]

@xmfcx Thank you for your comment! 😄

Why not https://readthedocs.org/ ?

Yes, Read the Docs can be a candidate.

IMO,

• Most developers are used to Markdown, not reStructuredText.
  • Read the Docs supports Markdown, but I guess it's a bit limited? (I'm not sure.)
    • https://docs.readthedocs.io/en/stable/intro/getting-started-with-sphinx.html#using-markdown-with-sphinx
• It's easier to use. (at least for me)
  • So I can maintain and it's ready to use now.
• It has more features like making the navigation tree as tabs.
  • (Note: I'm not familiar with the features of Read the Docs.)

(I've never heard of mkdocs before)

It's very widely used!

• It has 8.3k stars now and is actively developed.
• Eclipse iceoryx uses it.
  • https://iceoryx.io
• Read the Docs wrote about it.
  • https://docs.readthedocs.io/en/stable/intro/getting-started-with-mkdocs.html
• It was taken up on a blog post by GitHub.
  • https://github.blog/2021-12-03-release-radar-nov-2021/#material-for-mkdocs-8-0

[mitsudome-r]

Some of the features that we want:

• We want have searching result to be shown in the separate page like in read the docs
• We should have versioning of documents

[kenji-miyake]

We want have searching result to be shown in the separate page like in read the docs

This is available by this option if we use readthedocs theme.
https://www.mkdocs.org/dev-guide/themes/#include_search_page

However, material theme seems not supporting this.
https://github.com/squidfunk/mkdocs-material/blob/727f94f8676fea43a182703a558f08a19b6ceccb/mkdocs.yml#L47

@xmfcx Is this feature mandatory? If we'd like to simply share the URL, it's supported by material theme.
https://squidfunk.github.io/mkdocs-material/setup/setting-up-site-search/?q=test

We should have versioning of documents

This is available now by mike.

[xmfcx]

I like readthedocs theme more actually. The material theme feels more modern but incomplete, spaced out.

[kenji-miyake]

@xmfcx Thank you, I see. But I love the material theme.
So, since it depends on the person, I think it's better to decide by a questionnaire or something. Is that okay for you?

If it's okay, I'll send a PR for the comparison after I add some content.

Also, there is one more thing I'd like to clarify.
Is it okay for you to use MkDocs? I mean, are you concerned only about the theme?
Or do you want to use other tools such as Sphinx, mdBook, etc?

[xmfcx]

@xmfcx Thank you, I see. But I love the material theme. So, since it depends on the person, I think it's better to decide by a questionnaire or something. Is that okay for you?

If you want, you can arrange one in the slack. To me https://docs.ros.org/en/rolling/index.html looks like the perfect documentation style for me. It is structured and solid. https://iceoryx.io/v1.0.1/getting-started/what-is-iceoryx/ on the other hand looks so spaced out, empty and incomplete.

If it's okay, I'll send a PR for the comparison after I add some content.

I don't think that's necessary, we know how both look like.

Also, there is one more thing I'd like to clarify. Is it okay for you to use MkDocs? I mean, are you concerned only about the theme? Or do you want to use other tools such as Sphinx, mdBook, etc?

https://docs.readthedocs.io/en/stable/intro/getting-started-with-sphinx.html#using-markdown-with-sphinx this I think is our best bet since it has the markdown that we want to use and core readthedocs that I like.

[kenji-miyake]

on the other hand looks so spaced out, empty and incomplete.

Could you show the points you have concerns, in a picture like this?
Are the red rectangle areas what you concerned?

I don't think that's necessary, we know how both look like.

Yes, but I guess we need to compare not only the looking but also some features.
Material theme has many customizable features.

autoware-documentation/mkdocs.yaml

Lines 10 to 33 in 88163d1

	features:
	- navigation.expand
	- navigation.indexes
	- navigation.instant
	- navigation.sections
	- navigation.tabs
	- navigation.tabs.sticky
	- navigation.top
	favicon: assets/images/autoware-foundation.png
	icon:
	logo: fontawesome/solid/car
	repo: fontawesome/brands/github
	language: en
	palette:
	- scheme: default
	primary: white
	toggle:
	icon: material/weather-sunny
	name: Switch to dark mode
	- scheme: slate
	primary: grey
	toggle:
	icon: material/weather-night
	name: Switch to light mode

You can test the features here.
https://squidfunk.github.io/mkdocs-material/setup/setting-up-navigation/

https://docs.readthedocs.io/en/stable/intro/getting-started-with-sphinx.html#using-markdown-with-sphinx this I think is our best bet since it has the markdown that we want to use and core readthedocs that I like.

As mentioned here, my concern is whether we can use the full features, I'm not sure about that and it takes some time to learn that.

---

Anyway, as a result of https://gitlab.com/autowarefoundation/autoware-foundation/-/issues/198, we agreed to start with MkDocs and consider moving to Read the Docs later.

[alexandrx]

@kenji-miyake Regarding arguments in favour of mkdocs-materials or other, you could help us listing up some key open source projects using it. In particular, if ROS community also use it as main documentation platform, or there is a trend to, then there will not be many objections.

Similar to Doxygen, it seems capable of rendering LaTeX, so documentation involving some mathematical terms, diagrams, etc., should be possible.

[xmfcx]

@kenji-miyake Regarding arguments in favour of mkdocs-materials or other, you could help us listing up some key open source projects using it. In particular, if ROS community also use it as main documentation platform, or there is a trend to, then there will not be many objections.

He mentioned them in this comment above: #4 (comment)

[xmfcx]

@kenji-miyake

on the other hand looks so spaced out, empty and incomplete.

Could you show the points you have concerns, in a picture like this? Are the red rectangle areas what you concerned?

[stale]

Is this still relevant? If so, what is blocking it? Is there anything you can do to help move it forward?

This issue has been automatically marked as stale because it has not had recent activity. It will be closed if no further activity occurs.

[kenji-miyake]

@xmfcx Do you think we can close this and create a new issue if necessary in the future?

[kenji-miyake]

I assume yes.
#4 (comment)

[kenji-miyake]

Another user of MkDocs Material.
https://github.com/pi-hole/pi-hole
https://docs.pi-hole.net/