This is an archive of the discontinued LLVM Phabricator instance.

[FLANG] Pick `.md` files when building sphinx documentation.
ClosedPublic

Authored by sameeranjoshi on Aug 18 2020, 3:28 AM.

Details

Summary

Need to build sphinx using below flags to Cmake
-DLLVM_ENABLE_SPHINX=ON -DSPHINX_WARNINGS_AS_ERRORS=OFF.
Generate html docs using cmake target
docs-flang-html
Generated html files should be at build/tools/flang/docs/html.
Patch in series from the dicussion on review
https://reviews.llvm.org/D85828

After this patch the markdown docmentation must be written using guide in-
llvm/docs/MarkdownQuickstartTemplate.md

Diff Detail

Event Timeline

sameeranjoshi created this revision.Aug 18 2020, 3:28 AM
Herald added a project: Restricted Project. · View Herald TranscriptAug 18 2020, 3:28 AM
sameeranjoshi requested review of this revision.Aug 18 2020, 3:28 AM
sameeranjoshi edited the summary of this revision. (Show Details)Aug 18 2020, 3:29 AM
sameeranjoshi added a project: Restricted Project.
sscalpone requested changes to this revision.Aug 18 2020, 8:36 AM

Please add a note to the overview about this requirement:

After this patch the markdown docmentation must be written using guide in-
llvm/docs/MarkdownQuickstartTemplate.md

Please update the instructions for generating documentation in README.md.

flang/docs/conf.py
255–256

Maybe update the line "One line description of project" to be something like "A Fortran front end for LLVM"

This revision now requires changes to proceed.Aug 18 2020, 8:36 AM
sameeranjoshi marked an inline comment as done.Aug 18 2020, 12:48 PM
kiranchandramohan added inline comments.
flang/README.md
225

Nit: Suggestion: preferably be written in markdown(.md) documentation format -> preferably be written in markdown(.md) syntax
Nit: space between format and (.

flang/docs/conf.py
31

Is this over-riding the assignment to extensions above? If so can the one above be removed?

sameeranjoshi marked 2 inline comments as done.Aug 19 2020, 1:23 AM
sscalpone accepted this revision.Aug 22 2020, 8:39 AM

The install target required me to build all of the documentation. I do not think that is related to this change. Otherwise, the web pages rendered nicely.

This revision is now accepted and ready to land.Aug 22 2020, 8:39 AM

Thanks @sscalpone, this issue was mentioned long back during the doxygen related patches.
llvm, mlir and might be other projects in tree seem to show the same issue.
https://reviews.llvm.org/D78136#1987218

hans added a subscriber: hans.Aug 31 2020, 4:57 AM

I tried building the Flang docs with this applied, and they build fine, but show up empty in my web browser.

Looking at the generated Overview.html, it seems to be because of the comment header at the top, which looks like this in HTML:

  <!--===- docs/Overview.md <p>Part of the LLVM Project, under the Apache License v2.0 with LLVM Exceptions.
See https://llvm.org/LICENSE.txt for license information.
SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception</p>
<p>–&gt;</p>

It appears that the HTML comment is never terminated, because the --> has been turned into –&gt; by the tool.

I would suggest dropping the comment headers from the docs; other LLVM projects don't seem to have them. Or if they're considered important, maybe try one of the other techniques in https://stackoverflow.com/questions/4823468/comments-in-markdown

Hi @hans
The problem here is the version of recommonmark.
We strictly need version 0.5.0 or above.
See the note at https://www.sphinx-doc.org/en/master/usage/markdown.html#configuration
and https://github.com/llvm/llvm-project/blob/0fd425af071a9bc5c0891a4db09f4d9a466b7be9/flang/docs/conf.py#L44

I tried with the mentioned version and I can see the comments in the HTML files.
@sscalpone as well has verified it with recommonmark 0.6.0 version

Hopefully, @hans if you can verify it with a sample comment on your machine then I can revert the old patch D86875 and bring back licence text.

Thanks.

hans added a comment.Sep 9 2020, 5:10 AM

Hi @hans
The problem here is the version of recommonmark.
We strictly need version 0.5.0 or above.
See the note at https://www.sphinx-doc.org/en/master/usage/markdown.html#configuration
and https://github.com/llvm/llvm-project/blob/0fd425af071a9bc5c0891a4db09f4d9a466b7be9/flang/docs/conf.py#L44

I tried with the mentioned version and I can see the comments in the HTML files.
@sscalpone as well has verified it with recommonmark 0.6.0 version

Hopefully, @hans if you can verify it with a sample comment on your machine then I can revert the old patch D86875 and bring back licence text.

Thanks.

I don't have version 0.5.0 or above (I use the Debian package), but put the comment back in and I'll deal with it locally in my build.