Make Projects Documentation a fabulous experience

[Nlight91]

Check for existing issues

• Completed

Describe the feature

Concept

There are existing projects that scans other project and auto-build a documentation, my suggestion is to pick one of them (or more tedious, create one) and use it in a fully integrated way.

However, that is not all, the main concept that led me here, is that opening and editing the documentation of a library, function, class and methods that we are currently working on be accessible with just a combination of modifiers+(key || mouse button) press.

would it open a editing popup, or appear in a split is to be determined.
For the documentation formatting language, I suggest Markdown or reST (less widespread, but better features specs).
For the "doc editor window", it should offer IMO a wysiwyg mode by default with the focused line/paragraph being raw Markdown, and also offer a raw Markdown mode.

More details about the kind of documentation structure to pursue (IMO) in this post

Benefits

Not only it would favor a good documentation, a thing still often neglected. but it would also promote :

• a documentation organization standard, which if does spread wide enough throughout the industry, would greatly facilitate their consultation, out of habit.
• an ease for development, as one could consult the docs of whatever code portion he's working on and dismiss it with ease, which can be mandatory for complex projects. Allowing switching between reading/editing docs and editing code a fast and accessible process, makes the doc writing an incremental task done almost at the same time as writing the code, somewhat mimicking how the brain works, as it quickly navigates tasks all the time, in a non sequential way.
• allows for more code clarity by avoiding comments / docstrings cluttering in the code.

If applicable, add mockups / screenshots to help present your vision of the feature

No response

[jansol]

Markdown and some form of Doxygen/Javadoc style annotations are pretty widespread conventions in several languages already, improving the flow for editing those does sound nice.

[Nlight91]

improving the flow for editing those does sound nice.

You got it, that's exactly that ! thank you

[notpeter]

In the absence of specific actionable suggestions for improving the experiencing of writing project documentation I'm going to convert this to a discussion.

As someone who writes a lot of markdown documentation in Zed about Zed, I'd be very excited for suggestions on how to improve that process. Thanks for reporting.

[ryanwwest]

For the "doc editor window", it should offer IMO a wysiwyg mode by default with the focused line/paragraph being raw Markup, and also offer a raw Markdown mode.

This for Markdown, and support for adjustable line heights/image/hiding link syntax of e.g. Markdown when cursor isn't directly over it would be great for editing documentation, even without doing anything else. And just good in general - that would open up so many possibilities.

Basically the equivalent of Obsidian's Live Preview mode. I think a good deal of people would move over to Zed for their PKM/Zettelkasten systems if Markdown and other formats could be written and read nicely without a dual view of source/preview.

[pascalbehmenburg]

I for example would love to do so and also I see the benefit for people who are not that familiar with how documentation is generated. Especially in languages which they haven't used before and might not even know much about the ecosystem. If it would be possible to see the docs rendered or even explore them through some auto-generated tree (table-of-contents) + search, it would simply be amazing.

[Nlight91]

Yes ! I should have mentioned the Obsidian's Live Preview mode, as this is exactly what I had in mind for a wysiwyg

[harryjwright]

I'm trying to get some form of highlighting for my comments. I would be very happy with @ highlighting and a number of keywords I can assign.

In the C++ world, a lot of the current tools seem outdated (Dare I say it? Doxygen included). I would be happy with using whatever the IDE provided for a quick and easy solution.

[jansol]

As far as I'm aware Doxygen is still the state of the art for C++ documentation. If you know of better options it'd be more useful to also name them...

Highlighting for \brief/@brief and \param/@param is technically a relatively simple matter of editing the tree-sitter queries for each applicable language. The main bikeshedding is what to name the tokens so that they are consistent across all languages and can be themed reliably.

[harryjwright]

@jansol I've been considering doxide.

Tree-sitter is a foreign term to me. It does state on the website:

Doxide is written in C++ so that its primary users, C++ developers, can readily contribute. It uses Tree-sitter to parse C++.

I feel like this may be a relatively easy integration.

[Nlight91]

wouldn't it be an extension like Better comment for vsCode ? you could look it up, that seems to cover what you aim to achieve.

[Nlight91]

One aspect I think is important but clearly was omitted in my presentation (I'll add it right away), is the fact that auto-documentation tools seem to rely on comments and/or docstrings (python concept) while it may be good, it can actually turn into such a clutter to the code (IMO). What could make the accessible doc a great experience is the fact that the dev may be more inclined to not clutter the code with big comment blocks or docstrings (python concept). Indeed, why the need of big special comment blocks or strings when we have Treesiter and if the switch between code and docs is just a keypress away.

I don't know if a tool already exist that could just mirror the source code structure into a pre-structured empty documentation.

For example, let's imagine the following project file structure :

project folder
  o-lib
  | +-foo.py
  +-main.py

foo.py code :

CONST_FOO:int = 123

class Foo:
    def __init__(s, value:int):
        s.value = value

    def increment(s) -> int: 
        s.value += 1
        return s.value

def find( pattern:str, text:str ) -> str:
    return text.find(pattern)

main.py code :

from lib import foo

def main() -> None:
    a = foo.Foo(1)
    b = a.increment()
    print(f"hello {b.value} times")

if __name__ == "__main__" :
    main()

Now Zed could automatically create (at least) pre filled doc files for each libraries, where some dotfiles like .docignore could be used to skip some files, like here, main.py.

which here would give the following file hierarchy :

project folder
  o-doc
  | o-libraries
  | | +-foo.html <- (
  |                   auto-generated : creation, pre-filled class & methods & attributes, functions & parameters, constants 
  |                   user-generated : description of auto-generated elements, library summary and manual
  |                  )
  | +-module_index.html <--(fully auto-generated, hyperlinks to libraries)
  | +-global_index.html <--(fully auto-generated, hyperlinks to anchors of libraries, class, functions, global constants)
  | +-project presentation.html
  o-lib
  | +-foo.py
  +-main.py

While editing the documentation could be done with a markup language like markDown or reST for some portion, overall html pages stucture would be automatically generated and noneditable by the dev, like the outline of the current doc page.

If no documentation tools generic enough do exist to build these structures without relying on special comments or docstrings, Treesitter would be the obvious tool to use for a custom solution.

A visit to python docs and one of its module documentation are great example good documentation structure, IMHO.
And while visiting these pages do not show an example of the way the editing part could be presented, I think this already provides more body to the discussion.

back to summary

[jansol]

it can actually turn into such a clutter to the code (IMO).

This is easily solved by folding doc comments and docstrings away by default. Having the documentation directly in the code is in my experience the only way to actually keep it somewhat up to date though, so I would be very hesitant to move it away.

[pascalbehmenburg]

I strongly agree that in-code docs should be supported. The argument that the docs would be only one keystroke away seems bad imo. The same argument could be made for saying it is only one keystroke to collapse or jump over a docstring.

Personal opinion:
If I have to document code I want to see the code in front of me. I don't want to switch contexts and I don't want to be forced to have splits to see both. Also all of my projects already use in-code docs as many others do too.

Compromise:
It would be good if you could have in-code rendered markdown + a way of extracting the docs from code and seeing them in a completely different view with a table of contents. This view could also serve those that don't like in-code docs as it could be used for external docs too. It should also be possible to use external docs for additional pages which do not map to code. E.g. introduction pages, getting started, etc.

Finally support for both in-code- and external docs is necessary to make both camps happy and offer a diverse enough experience to be an actual replacement for existing tools and existing code bases.

[Nlight91]

Nobody would be prevented to use comments and docstring mind you, that would be rather silly. It wouldn't prevent in any way anyone to keep doing things the way they've always done...

I don't understand why having an option offered to the dev is a problem.

This is easily solved by folding doc comments and docstrings away by default

Folding is still visual clutter that I personally hate. But hey, keep using it, it's not going anywhere.

Sometimes, some functions/method/class needs a lot of context and/or examples to be fully understood. One could argue this is where one should write a separate documentation instead of a docstring, or even re-design... but sometimes, stuff are just complex like that, and yes external doc is then better suited. Hence an easy access to appropriate external doc section readily editable.

sometimes, you may be consulting the code in the web browser with barebone functionality, admittedly a rare occurrence, but still. Having a full manual between the signature of a function and its body is... not great.

I maybe wrong but why do tools such as doxygen exist ? IMO One of the reason is lazyness, cause writing all the html/css boiler plate is tremendously tedious, opening an editor for this stuff, navigating to the right section, etc... is BOOOOORING. So yeah, my proposition share a similar goal as doxygen, that just potentially removes clutter and give the documentation its proper place as well as an easy access.

What I propose is IMO, the best of both worlds while not forcing anyone to adopt this doc workflow.