Tool to generate code docs

classic Classic list List threaded Threaded
6 messages Options
Reply | Threaded
Open this post in threaded view
|

Tool to generate code docs

Hubert Tong via cfe-dev
Hi team clang,

I am interested in developing a tool to generate code documentation.  So I am wondering if this project already exists and I could collaborate with you. If not, I can start this project and I would still love to collaborate with anyone who's interested.

Kindly,

Anshil

_______________________________________________
cfe-dev mailing list
[hidden email]
https://lists.llvm.org/cgi-bin/mailman/listinfo/cfe-dev
Reply | Threaded
Open this post in threaded view
|

Re: Tool to generate code docs

Hubert Tong via cfe-dev
Seems there might already be one under the clang umbrella:
https://clang.llvm.org/extra/clang-doc.html - but I'm not sure how old
it is and whether it's being actively developed.

On Fri, Aug 21, 2020 at 10:34 PM Anshil Gandhi via cfe-dev
<[hidden email]> wrote:

>
> Hi team clang,
>
> I am interested in developing a tool to generate code documentation.  So I am wondering if this project already exists and I could collaborate with you. If not, I can start this project and I would still love to collaborate with anyone who's interested.
>
> Kindly,
>
> Anshil
> _______________________________________________
> cfe-dev mailing list
> [hidden email]
> https://lists.llvm.org/cgi-bin/mailman/listinfo/cfe-dev
_______________________________________________
cfe-dev mailing list
[hidden email]
https://lists.llvm.org/cgi-bin/mailman/listinfo/cfe-dev
Reply | Threaded
Open this post in threaded view
|

Re: Tool to generate code docs

Hubert Tong via cfe-dev
Thanks, I'll check it out.

On Fri, Aug 21, 2020 at 11:43 PM David Blaikie <[hidden email]> wrote:
Seems there might already be one under the clang umbrella:
https://clang.llvm.org/extra/clang-doc.html - but I'm not sure how old
it is and whether it's being actively developed.

On Fri, Aug 21, 2020 at 10:34 PM Anshil Gandhi via cfe-dev
<[hidden email]> wrote:
>
> Hi team clang,
>
> I am interested in developing a tool to generate code documentation.  So I am wondering if this project already exists and I could collaborate with you. If not, I can start this project and I would still love to collaborate with anyone who's interested.
>
> Kindly,
>
> Anshil
> _______________________________________________
> cfe-dev mailing list
> [hidden email]
> https://lists.llvm.org/cgi-bin/mailman/listinfo/cfe-dev

_______________________________________________
cfe-dev mailing list
[hidden email]
https://lists.llvm.org/cgi-bin/mailman/listinfo/cfe-dev
Reply | Threaded
Open this post in threaded view
|

Re: Tool to generate code docs

Hubert Tong via cfe-dev
I'd recommend Julie's lighting talk from 2018 LLVM Developers’ Meeting: “clang-doc: an elegant generator for more civilized documentation” to learn more about the tool.

We have a bot that continuously builds and publishes HTML documentation generated from Fuchsia's codebase to fuchsia-docs.firebaseapp.com/cpp/ to ensure that the tool keeps working. The tools itself has been stable and performant. However, if you open that site, you'll probably notice that the generated output needs some work (try https://fuchsia-docs.firebaseapp.com/cpp/zx/index.html to see a more concrete example).

What we really need is someone with HTML, JS and CSS experience. For example, the navigation is currently loaded synchronously and always rendered in its entirety which is a problem for larger projects, which is why the page load takes so long for the link I gave above. The content itself also lacks any styling. Unfortunately, we don't have that experience on our team and we could really use some help here.

I'm happy to review clang-doc changes if this is something you'd be interested in contributing to.

On Fri, Aug 21, 2020 at 10:48 PM Anshil Gandhi via cfe-dev <[hidden email]> wrote:
Thanks, I'll check it out.

On Fri, Aug 21, 2020 at 11:43 PM David Blaikie <[hidden email]> wrote:
Seems there might already be one under the clang umbrella:
https://clang.llvm.org/extra/clang-doc.html - but I'm not sure how old
it is and whether it's being actively developed.

On Fri, Aug 21, 2020 at 10:34 PM Anshil Gandhi via cfe-dev
<[hidden email]> wrote:
>
> Hi team clang,
>
> I am interested in developing a tool to generate code documentation.  So I am wondering if this project already exists and I could collaborate with you. If not, I can start this project and I would still love to collaborate with anyone who's interested.
>
> Kindly,
>
> Anshil
> _______________________________________________
> cfe-dev mailing list
> [hidden email]
> https://lists.llvm.org/cgi-bin/mailman/listinfo/cfe-dev
_______________________________________________
cfe-dev mailing list
[hidden email]
https://lists.llvm.org/cgi-bin/mailman/listinfo/cfe-dev

_______________________________________________
cfe-dev mailing list
[hidden email]
https://lists.llvm.org/cgi-bin/mailman/listinfo/cfe-dev
Reply | Threaded
Open this post in threaded view
|

Re: Tool to generate code docs

Hubert Tong via cfe-dev
In reply to this post by Hubert Tong via cfe-dev
There's also https://github.com/standardese/standardese

On Sat, 22 Aug 2020 at 07:43, David Blaikie via cfe-dev
<[hidden email]> wrote:

>
> Seems there might already be one under the clang umbrella:
> https://clang.llvm.org/extra/clang-doc.html - but I'm not sure how old
> it is and whether it's being actively developed.
>
> On Fri, Aug 21, 2020 at 10:34 PM Anshil Gandhi via cfe-dev
> <[hidden email]> wrote:
> >
> > Hi team clang,
> >
> > I am interested in developing a tool to generate code documentation.  So I am wondering if this project already exists and I could collaborate with you. If not, I can start this project and I would still love to collaborate with anyone who's interested.
> >
> > Kindly,
> >
> > Anshil
> > _______________________________________________
> > cfe-dev mailing list
> > [hidden email]
> > https://lists.llvm.org/cgi-bin/mailman/listinfo/cfe-dev
> _______________________________________________
> cfe-dev mailing list
> [hidden email]
> https://lists.llvm.org/cgi-bin/mailman/listinfo/cfe-dev



--
You can get very substantial performance improvements
by not doing the right thing. - Scott Meyers, An Effective C++11/14 Sampler
So if you're looking for a completely portable, 100% standards-conformant way
to get the wrong information: this is what you want. - Scott Meyers (C++TDaWYK)
_______________________________________________
cfe-dev mailing list
[hidden email]
https://lists.llvm.org/cgi-bin/mailman/listinfo/cfe-dev
Reply | Threaded
Open this post in threaded view
|

Re: Tool to generate code docs

Hubert Tong via cfe-dev
In reply to this post by Hubert Tong via cfe-dev
I'd recommend https://llvm.org/docs/GettingStarted.html which is a useful starting point.

clang-doc is a part of clang-tools-extra, so to build it you can use:

git clone https://github.com/llvm/llvm-project.git
cd llvm-project
mkdir build
cd build
cmake -G Ninja -DCMAKE_EXPORT_COMPILE_COMMANDS -DLLVM_ENABLE_PROJECTS='clang;clang-tools-extra' ../llvm
ninja clang-doc

To use it, you can use the compilation database (see https://clang.llvm.org/docs/JSONCompilationDatabase.html for more information on compilation databse) generated by the command above as:

./bin/clang-doc --format=html --output=docs compile_commands.json

This generates documentation for LLVM, clang and clang-tools-extra in the docs directory.

Once you have a patch, I'd recommend following https://llvm.org/docs/Contributing.html.

On Sat, Aug 22, 2020 at 12:54 AM Anshil Gandhi <[hidden email]> wrote:
I found bugs in bugzilla. So I guess a better question would be how to get started.

On Sat, Aug 22, 2020 at 1:46 AM Anshil Gandhi <[hidden email]> wrote:
I would be happy to help out! I have an intermediate level experience with HTML, CSS and JS but I think I can pick them up along the way as needed. So how can I find specific issues related to clang-doc?

On Sat, Aug 22, 2020 at 1:17 AM Petr Hosek <[hidden email]> wrote:
I'd recommend Julie's lighting talk from 2018 LLVM Developers’ Meeting: “clang-doc: an elegant generator for more civilized documentation” to learn more about the tool.

We have a bot that continuously builds and publishes HTML documentation generated from Fuchsia's codebase to fuchsia-docs.firebaseapp.com/cpp/ to ensure that the tool keeps working. The tools itself has been stable and performant. However, if you open that site, you'll probably notice that the generated output needs some work (try https://fuchsia-docs.firebaseapp.com/cpp/zx/index.html to see a more concrete example).

What we really need is someone with HTML, JS and CSS experience. For example, the navigation is currently loaded synchronously and always rendered in its entirety which is a problem for larger projects, which is why the page load takes so long for the link I gave above. The content itself also lacks any styling. Unfortunately, we don't have that experience on our team and we could really use some help here.

I'm happy to review clang-doc changes if this is something you'd be interested in contributing to.

On Fri, Aug 21, 2020 at 10:48 PM Anshil Gandhi via cfe-dev <[hidden email]> wrote:
Thanks, I'll check it out.

On Fri, Aug 21, 2020 at 11:43 PM David Blaikie <[hidden email]> wrote:
Seems there might already be one under the clang umbrella:
https://clang.llvm.org/extra/clang-doc.html - but I'm not sure how old
it is and whether it's being actively developed.

On Fri, Aug 21, 2020 at 10:34 PM Anshil Gandhi via cfe-dev
<[hidden email]> wrote:
>
> Hi team clang,
>
> I am interested in developing a tool to generate code documentation.  So I am wondering if this project already exists and I could collaborate with you. If not, I can start this project and I would still love to collaborate with anyone who's interested.
>
> Kindly,
>
> Anshil
> _______________________________________________
> cfe-dev mailing list
> [hidden email]
> https://lists.llvm.org/cgi-bin/mailman/listinfo/cfe-dev
_______________________________________________
cfe-dev mailing list
[hidden email]
https://lists.llvm.org/cgi-bin/mailman/listinfo/cfe-dev

_______________________________________________
cfe-dev mailing list
[hidden email]
https://lists.llvm.org/cgi-bin/mailman/listinfo/cfe-dev