docco/pycco style side by side code and annotated comments

[mugli]

Can we have a code view inspired by docco?
The implementation can be a theme or different view, whatever makes sense.

Key ideas:

• Process markdown in comments
• Show comment and code side by side, the result becomes more readable.

Examples:

• https://pycco-docs.github.io/pycco/
• http://gitlet.maryrosecook.com/docs/gitlet.html
• https://khamidou.com/compilers/lisp.py/

golds renders much more powerful view for code navigation than docco (and it's ports). If we have this additional feature, I believe it can be a powerful tool for code reading enthusiasts who also like to produce annotated source code (as artefacts) of popular/well-written codebases (like this or this, but much better).

[zigo101]

This is an interesting UE design.
I will add a todo list for this, but I'm afraid that I will have not enough time to implemented it in a near future version.
And content richness is not now (edited) viewed more important than UI/UE at the current phase.

Thanks for the suggestion.

[mugli]

Thank you for considering it for future.

I had an itch and wanted to take a stab to see how it'd look with golds, so I did some quick hack to incorporate literate style source view.

• Here's the commit in my fork: mugli@4375841
• Here's how a page looks now: https://mugli.github.io/tmp-literate-golds/src/golang.org/x/pkgsite/internal/auth/auth.go.html

There are some edge cases that are not handled yet. For example, a lot of time comments contain example code. Those currently looks broken in this structure. Also, Go directives are not handled separately from regular comments.

Feature wise, markdown in comment is not handled yet. It might be useful if someone wants to annotate the code.

If you think it can be merged with some tweaks, I can prepare a PR if you want. But I certainly understand it's not a priority now, so totally fine if you don't want that at this moment. I'll try to maintain the fork as long as I'm using this feature.

[zigo101]

Aha, you have made some tweaks on the Golds projects.
That is really cool. The code base of Golds has not been cleaned yet.
Some parts of it might be hard to understand.

Yes, I couldn't merge the PR now. It is quality unrelated.
It is just because the change is some big.

Markdown renderer is a good idea but it looks markdown is not used popularly for documents in Go world.
But it is really a good idea to recommend people to use markdown in documents.

Do you think it is okay to implement the whole feature mainly in JS at client side?