[cfe-dev] Tool to generate code docs

[Petr Hosek 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 <gandhi21299 at gmail.com>
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 <gandhi21299 at gmail.com>
> 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 <phosek at chromium.org> wrote:
>>
>>> I'd recommend Julie's lighting talk from 2018 LLVM Developers’ Meeting: “clang-doc:
>>> an elegant generator for more civilized documentation
>>> <https://www.youtube.com/watch?v=bTzvPhKN0YI>” 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 <
>>> cfe-dev at lists.llvm.org> wrote:
>>>
>>>> Thanks, I'll check it out.
>>>>
>>>> On Fri, Aug 21, 2020 at 11:43 PM David Blaikie <dblaikie at gmail.com>
>>>> 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
>>>>> <cfe-dev at lists.llvm.org> 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
>>>>> > cfe-dev at lists.llvm.org
>>>>> > https://lists.llvm.org/cgi-bin/mailman/listinfo/cfe-dev
>>>>>
>>>> _______________________________________________
>>>> cfe-dev mailing list
>>>> cfe-dev at lists.llvm.org
>>>> https://lists.llvm.org/cgi-bin/mailman/listinfo/cfe-dev
>>>>
>>>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.llvm.org/pipermail/cfe-dev/attachments/20200823/f0396286/attachment.html>