Comments (16)
@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.)
- 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
.)
- (Note: I'm not familiar with the features of
(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.
Read the Docs
wrote about it.- It was taken up on a blog post by GitHub.
from autoware-documentation.
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?
from autoware-documentation.
We'll set up mkdocs-material for this repository as well and try to prepare the equivalent documents as Autoware.Auto.
from autoware-documentation.
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 )
from autoware-documentation.
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
from autoware-documentation.
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.
from autoware-documentation.
I like readthedocs
theme more actually. The material
theme feels more modern but incomplete, spaced out.
from autoware-documentation.
@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?
from autoware-documentation.
@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 asSphinx
,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.
from autoware-documentation.
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
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.
from autoware-documentation.
@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.
from autoware-documentation.
@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)
from autoware-documentation.
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.
from autoware-documentation.
@xmfcx Do you think we can close this and create a new issue if necessary in the future?
from autoware-documentation.
I assume yes.
#4 (comment)
from autoware-documentation.
Another user of MkDocs Material.
https://github.com/pi-hole/pi-hole
https://docs.pi-hole.net/
from autoware-documentation.
Related Issues (20)
- Add documentation for perception interface HOT 1
- Image and Latex Equations are not properly loaded/rendered HOT 4
- No progress update using rocker with docker installation (How to set up a workspace)
- Add Frequently Asked Question page HOT 1
- Add documentation for map interface HOT 1
- DevOps Dojo: ROS Node Configuration - JSON Schema to MD-Table for Web Documentation HOT 6
- DevOps Dojo: ROS Node Configuration - Update Parameter Contribution Guidelines HOT 2
- Establish and document the versioning system for the autoware_msgs HOT 2
- Add documentation for Creating vehicle and sensor description HOT 2
- Add documentation on how to add a new localization node in autoware HOT 1
- Fill the documentation of "Creating vehicle interface for ackerman kinematic model"
- The link to the Autoware concepts documentation page may be broken. HOT 2
- Add documentation on how to guide autoware meta-repository
- "Behavior Planner" calculates "path", not "trajectory".
- Broken Links Issue Tracking HOT 4
- Update Autoware Integration Document HOT 1
- Update DDS isolation instructions for shared networks in Autoware HOT 4
- Add documentation how to train traffic light fine detector model HOT 1
- Update docker installation documentation
- Add docs for guiding the developers on finding, diagnosing, and fixing scenarios in Autoware HOT 1
Recommend Projects
-
React
A declarative, efficient, and flexible JavaScript library for building user interfaces.
-
Vue.js
🖖 Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.
-
Typescript
TypeScript is a superset of JavaScript that compiles to clean JavaScript output.
-
TensorFlow
An Open Source Machine Learning Framework for Everyone
-
Django
The Web framework for perfectionists with deadlines.
-
Laravel
A PHP framework for web artisans
-
D3
Bring data to life with SVG, Canvas and HTML. 📊📈🎉
-
Recommend Topics
-
javascript
JavaScript (JS) is a lightweight interpreted programming language with first-class functions.
-
web
Some thing interesting about web. New door for the world.
-
server
A server is a program made to process requests and deliver data to clients.
-
Machine learning
Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.
-
Visualization
Some thing interesting about visualization, use data art
-
Game
Some thing interesting about game, make everyone happy.
Recommend Org
-
Facebook
We are working to build community through open source technology. NB: members must have two-factor auth.
-
Microsoft
Open source projects and samples from Microsoft.
-
Google
Google ❤️ Open Source for everyone.
-
Alibaba
Alibaba Open Source for everyone
-
D3
Data-Driven Documents codes.
-
Tencent
China tencent open source team.
from autoware-documentation.