carbon-lang
carbon-lang copied to clipboard
carbon-language
Need a website for documentation
Can we get a simple readthedocs type of website for the carbon's documentation. Because its hard to navigate in github and the readability is not very good.
Its easy to convert the existing readme to documentation website using tools like mkdocs, kramdown, jekyll etc!
I made a simple script for converting the markdown files under docs/ to HTML using pandoc: https://github.com/emlai/carbon-lang/commit/200eeb3de40303e11aa0a278008eadae71bd031c
You can see the result here: https://emlai.github.io/
It's still missing styles and a navigation bar, but the links seem to be working correctly.
I updated my branch to use mkdocs after I got it to handle absolute markdown links correctly. It adds a theme, a navbar, and a search, so it looks much better now: https://emlai.github.io/
There's still stuff to do:
- It would be better to show the repository root readme on the front page.
- Create a GitHub action for auto-deploying the site.
- Organize the code snippets in a better way. Currently they're under
Images > Front page snippets for Carbon. - Replace the logo with the Carbon logo.
- Customize the theme to make it look less stock and more "Carbony".
- etc.
@Nike682631 If you want to help, we can sync on the Discord!
If you're working on a GitHub pages PR, one thing we've been cautious of is developers interpreting a documentation website as implicit encouragement to use Carbon in production. However, hopefully it's clear to most that Carbon isn't there.
To address that concern, can you maybe add a reminder at the top that Carbon is experimental and not intended for use in applications, linking to https://github.com/carbon-language/carbon-lang/blob/trunk/docs/project/faq.md#how-soon-can-we-use-carbon
I'm moving this to be an issue for leads as they've requested review (a proposal and some details of tradeoffs may be needed, and there's hesitance about whether a website makes sense for Carbon Language at this time). Just to note references: #1526 provides an implementation, and a sample is at https://emlai.github.io/.
A website would be good for documentation. Also if there is an option for converting to pdf. It would be helpful
A website would be good for documentation. Also if there is an option for converting to pdf. It would be helpful
our best bet is rust-lang/mdbook
https://github.com/rust-lang/mdBook
@emlai I would be keen to collaborate on replicating your proposed website with my website generator nift.dev. Three dot point sales pitch:
- Has LuaJIT embedded (though if there's a faster md->html converter can use that too);
- Benchmarks way faster than even Hugo (who still brand themselves as world's fastest) plus has had incremental builds since 2015, people should have near instant build times when working on the website rather than having to twiddle their thumbs waiting for builds to finish;
- Is developed in C++ which might be favourable to future Carbon devs who are likely to have C++ backgrounds (one common sentiment among web developers is they prefer to use tools developed in the languages they know like js, c++/carbon devs may be similar);
We triage inactive PRs and issues in order to make it easier to find active work. If this issue should remain active or becomes active again, please comment or remove the inactive label. The long term label can also be added for issues which are expected to take time.
This issue is labeled inactive because the last activity was over 90 days ago.
![github-actions[bot] avatar](https://avatars.githubusercontent.com/in/15368?v=4 "Published by a pub.dev verified publisher"){kind=small}
can I work on this? I came here from GsoC organization page........
We use the "leads question" label for things that are awaiting a decision from the project leads about how to proceed. Until they decide that they want a website, and what they want from such, this isn't something that we would proceed on.
(note, it may help to discuss options on #gsoc on Discord)
I would like to work on this. I have prior experience in writing documentation. Please assign me this issue. @jonmeow
It is possible that a website, easily browsable and indexed by search engines, would help people who are not as comfortable with git and markdown as our current approach. It is definitely a more immersive experience to click around reading things and trying to see what Carbon is and isn't without having to think about the way the information is stored and presented. It would need to be generated from the material in git, so that it could not get out of sync, and we might need a "build step" when any of the source material changes.
We would need to be absolutely clear that this is a website for those helping to build Carbon, not for those wanting to use Carbon, and the the site going live doesn't carry information like "Carbon is open for business!" A top banner as in the provided example https://emlai.github.io/ would work, along with explanations in the places we provide links to this new site.
I would like to work on this...
@ThePhilosopher4097 , we typically don't assign issues to people, see https://github.com/carbon-language/carbon-lang/blob/trunk/CONTRIBUTING.md#triage-analyze-or-address-bugs
