[cfe-commits] r170260 - in /cfe/trunk/docs: AnalyzerRegions.rst analyzer/AnalyzerRegions.rst index.rst

[Sean Silva]

> Previously, I kind of considered docs/ to be more associated with lib/ than with www/.

Woah, I didn't even know that there was that weird www/ directory in
the clang tree. Personally, I would like to see that abolished to keep
things consistent with how LLVM's documentation is organized (www/ is
orthogonal and kept in a separate repo). Things like www/hacking.html
and www/get_started.html should be in docs IMO, for consistency with
e.g. <http://llvm.org/docs/GettingStarted.html>. I think my gut
feeling is that anything which is targeted at people who work with
clang's code should be in docs/, while things like "the latest build
of the analyzer" or a live demo should be in www/.

> But it has its own website, clang-analyzer.llvm.org.

I'm curious about this. Why is it not sufficient to simply be
clang.llvm.org/analyzer (which works)?

> The answer to my question might just be "exclude docs/analyzer/ from the Sphinx build" and eventually "make a separate build for docs/analyzer/ that shows up at http://clang-analyzer.llvm.org/docs/."

I would personally like to keep the documentation unified. It should
be sufficient to just have the analyzer docs inside docs/analyzer/ and
link to there/redirect as needed.

-- Sean Silva

On Mon, Dec 17, 2012 at 7:23 PM, Jordan Rose <jordan_rose at apple.com> wrote:
>
> On Dec 17, 2012, at 18:18 , Sean Silva <silvas at purdue.edu> wrote:
>
>> On Mon, Dec 17, 2012 at 4:08 PM, Ted Kremenek <kremenek at apple.com> wrote:
>>> We should just delete it.  Nobody is using it.  When we decide to properly document this, we can resuscitate the content from version control and bring it up to date.
>>
>> Ok, I nuked it in r170401.
>
> Thanks, Sean. Sorry for the mess.
>
>
>
>> Jordan, somehow the message that Ted quoted didn't make it to me, so
>> I'll reply here:
>>
>>> On Dec 17, 2012, at 9:28 AM, Jordan Rose <jordan_rose at apple.com> wrote:
>>> Sean, what do you think we should do with the analyzer docs in general?
>>
>> I generally think that the documentation for a specific piece of code
>> should live in the same repository as the code itself. The rationale
>> is to guarantee that any developer working on the code has immediate
>> access to the documentation so that they can update it/add to it.
>
> Yes, I agree with that. The analyzer lives in lib/StaticAnalyzer and include/clang/StaticAnalyzer. But it has its own website, clang-analyzer.llvm.org. Previously, I kind of considered docs/ to be more associated with lib/ than with www/, which made docs/analyzer/ a reasonable place to put all this (cf. the text-based reference files in there now).
>
> The answer to my question might just be "exclude docs/analyzer/ from the Sphinx build" and eventually "make a separate build for docs/analyzer/ that shows up at http://clang-analyzer.llvm.org/docs/."
>