WIP Dear ImGui Documentation Website

PossiblyAShrub commented 3 years ago

TLDR

I've started work on a documentation website for Dear ImGui, currently visible here https://possiblyashrub.github.io/imgui-docs/#/. This is a tracking issue to:

document my progress
collect feedback, and
get visibility on the project

Overview

I originally announced this on the discord server:

I had a bit of free time at the start of the week, so I started working on higher-level documentation for Dear ImGui. Ideally, this would be a website we can point to, rather than markdown files scattered around the docs folder/wiki. It is certainly not a replacement for documentation in the form of in-code comments and the demo window. But, it's a great place to centralize articles like the FAQ and a WIP getting started guide I've drafted.

So far I've created a live demo (https://possiblyashrub.github.io/imgui-docs/#/) and pushed all the code to a Github repository (https://github.com/PossiblyAShrub/imgui-docs).

Hopefully this is something that can eventually become official Dear ImGui documentation.

The idea was to create a website that could host numerous articles/guides on the usage/integration of Dear ImGui. Most of these articles already exist, but they've been scattered about in the wiki, docs folder, or numerous other articles/projects by Dear ImGui community members.

Progress

I've opened this as a tracking issue, as I would eventually like to make this official Dear ImGui documentation. However, there is some work to be done. There are plenty of wonderful examples/guides written by many of you (Dear ImGui users) that would be awesome to have on the documentation website.

So far I have:

[x] Created the website (using a tool called Docsify), where one can write articles in pure markdown, and have them automatically transformed into HTML on the fly in your browser (this is cached and is quite fast).
[x] Moved most of the docs/ folder into the website
[x] Started a WIP getting-started guide for newcomers
[x] documentation versioning (ie. site path prefixes: /docs/latest or /docs/1.81)

What's next:
- [ ] Finish the getting-started guide (Omar has given me some useful feedback on the existing guide)
- [ ] Finish copying over documentation that currently lives in the wiki
- [ ] it would also be cool to integrate @pthom 's interactive manual (#3342) directly into the website
- [ ] the Automation / Testing / Visual documentation framework (#435) could be used to autogen screenshots of the results of code snippets
- Writing more articles/adding existing articles on topics such as:
  - [ ] layout
  - [ ] tables
  - [ ] docking
  - [ ] drag & drop
  - [ ] tree view
  - etc

If you have any suggestions to improve the documentation, or know of any guides (there exist many excellent gists explaining various topics), feel free to post them below. If you find errors in the documentation or want to make an addition yourself; I've hosted the source on a GitHub repo here (https://github.com/PossiblyAShrub/imgui-docs), feel free to make an issue/pr over there to prevent noise in this issue.

Thank you!

aiekick commented 3 years ago

its a nice work

pthom commented 3 years ago

Nice job!

it would also be cool to integrate @pthom 's interactive manual (#3342) directly into the website

A link to the manual is of course possible. The current url is https://pthom.github.io/imgui_manual_online/ or for direct access, https://pthom.github.io/imgui_manual_online/manual/imgui_manual.html

Concerning an integration into the website, this could be possible and would make me happy, but it would require a way to integrate and maintain the compiled emscripten output to the website.

FYI I am working on PR related to this manual in order to add some modification related to the manual into imgui_demo.cpp

ocornut commented 3 years ago

Thanks for doing this!

FYI I recently revamped the wiki and added a link to imgui_manual from there. https://github.com/ocornut/imgui/wiki

I suppose there is quite an overlap with the purpose of the wiki, but if we end up having a nicer solution outside of wiki I am in favor or transitioning. The fact it is also Markdown is particularly good there since some of the articles are identical.

(I would also consider seeing if some of that contents may be best expressed on the wiki)

One thing I mentioned the other day is, it is good to find medium and locations were people can work without requiring my scrutiny or approval on everything. Things don't have to be perfect and the more people feel at easy with writing and editing stuff, the faster we'll get to good documentation.

PossiblyAShrub commented 3 years ago

@pthom

A link to the manual is of course possible.

I've just pushed an update linking to the manual.

Concerning an integration into the website, this could be possible and would make me happy, but it would require a way to integrate and maintain the compiled emscripten output to the website.

I can figure out how to use Github actions to do this automatically. So CI would not be an issue. About integrating the manual into the documentation website; with your new PR and linking to Dear ImGui source, would it be possible to also link directly to the docs/wiki? I could imagine an index page that would simply be the demo window. Then, using your demo marker linking system, we could link to different parts of the documentation website directly from the demo window.

@ocornut

I suppose there is quite an overlap with the purpose of the wiki, but if we end up having a nicer solution outside of wiki I am in favor or transitioning. The fact it is also Markdown is particularly good there since some of the articles are identical.

(I would also consider seeing if some of that contents may be best expressed on the wiki)

Yes, this was the primary goal of keeping all documentation in Markdown. I would agree, that for the time being, sharing articles between the website and wiki would be wise.

I've still been working mostly on the getting started guide. I would argue it's one of the most crucial parts of the documentation and therefore deserves the most scrutiny. However, I will soon be done writing the guide and would like to copy it over to the wiki. When I copy it over, would you prefer that I first open a PR? Or would you prefer I just create a wiki page about it, and notify you in this thread?

rlalance commented 2 years ago

That interactive manual is mind blowing. I passed this to colleagues already :)

Thank you!

geocine commented 2 years ago

Thanks for doing this, I was looking for a documentation and it led me here.

pthom commented 2 years ago

@PossiblyAShrub : I added a link to your documentation website in the interactive manual website:

ocornut / imgui