-
Notifications
You must be signed in to change notification settings - Fork 13.6k
[Flang] Add Sphinx man page and html support for Flang #141882
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
base: main
Are you sure you want to change the base?
[Flang] Add Sphinx man page and html support for Flang #141882
Conversation
Thank you for submitting a Pull Request (PR) to the LLVM Project! This PR will be automatically labeled and the relevant teams will be notified. If you wish to, you can add reviewers by using the "Reviewers" section on this page. If this is not working for you, it is probably because you do not have write permissions for the repository. In which case you can instead tag reviewers by name in a comment by using If you have received no comments on your PR for a week, you can request a review by "ping"ing the PR by adding a comment “Ping”. The common courtesy "ping" rate is once a week. Please remember that you are asking for valuable time from other developers. If you have further questions, they may be answered by the LLVM GitHub User Guide. You can also ask questions in a comment on this PR, on the LLVM Discord or on the forums. |
@pawosm-arm -- Sorry to tag you explicitly, I do not have access to formally request reviews using the Reviewers section. |
No worries, I will look into it today. |
You can test this locally with the following command:darker --check --diff -r HEAD~1...HEAD flang/docs/conf.py View the diff from darker here.--- conf.py 2025-06-02 20:59:23.000000 +0000
+++ conf.py 2025-06-02 21:01:52.374223 +0000
@@ -229,11 +229,13 @@
# -- Options for manual page output --------------------------------------------
# One entry per manual page. List of tuples
# (source start file, name, description, authors, manual section).
-man_pages = [("index", "flang", "Flang Documentation (In Progress)", ["Flang Contributors"], 1)]
+man_pages = [
+ ("index", "flang", "Flang Documentation (In Progress)", ["Flang Contributors"], 1)
+]
# If true, show URL addresses after external links.
# man_show_urls = False
|
I think more people need to look into it. AFAIR the plan was that flang does not use the |
@pawosm-arm, thanks for looking into it. I got rid of the |
|
It did not seem like the build process got affected locally for me. Is there any other way of testing this out? |
Can you enable |
@kiranchandramohan -- this runs for me successfully and does not interfere with the placeholder file. The final |
What about the man pages and its contents. Is it the empty file or the one produced by tablegen? |
As I mentioned the man page produced at |
Can we do something similar to https://reviews.llvm.org/D128650 to avoid needing dummy |
@kiranchandramohan, I removed the placeholder |
It might not be ok. If the buildkite fails, as it does here, it will probably break buildbots too. I am not sure what is causing this though. |
Looking further into it. |
@kiranchandramohan @tarunprabhu, what do you guys think about modifying
|
I would prefer something like https://reviews.llvm.org/D128650 where the generated md/rst files are copied by the |
4f24ea6
to
bee779e
Compare
Hi @kiranchandramohan @tarunprabhu, with my latest commit the html target is built without any warnings. When I trigger the man build via
If we build with |
1d69ea5
to
cd886e1
Compare
@kiranchandramohan, @tarunprabhu, @pawosm-arm |
Not sure what is the ultimate scope of this PR, the flang manpage is indeed being generated. There are some observations though, but I'm not sure if this is the PR which should address them. Namely:
I like the fact that this page finally generates easily with no need for extensive CMake configuring. |
I think the man page is intended to be that way since all the documentation is built into |
I agree that there might be some more things to iron out but I think this patch has already touched quite a bit of CMake config and conf.py. It might be suitable to create another issue and address the issues in another PR as it is out of scope for the issue this is linked to. |
What I meant is this seems unusual. Compare these:
|
Ah ok, I see your point. I will defer this to someone who knows the expected size or if it really is meant to be that big. |
477e824
to
ae70eed
Compare
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Thanks for the changes. This looks OK to me. I have a question inline.
LGTM. Please wait for @tarunprabhu and @pawosm-arm
add_sphinx_target(man flang) | ||
add_sphinx_target(man flang SOURCE_DIR "${CMAKE_CURRENT_BINARY_DIR}/Source") | ||
add_dependencies(docs-flang-man gen-FlangCommandLineReference.rst) | ||
add_dependencies(docs-flang-man copy-flang-src-docs) |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
copy-flang-src-docs
seems to depend on gen-FlangCommandLineReference.rst
in the definition above. So is it required to add the dependence on gen-FlangCommandLineReference.rst
again?
Also, where is gen-FlangCommandLineReference.rst
defined?
This patch enables building Flang man pages by: - Adding a `man_pages` entry in flang/docs/conf.py for Sphinx man builder. - Adding a minimal `index.rst` as the master document. - Adding placeholder `.rst` files for FIRLangRef and FlangCommandLineReference to fix toctree references. These changes unblock builds using `-DLLVM_BUILD_MANPAGES=ON` and allow `ninja docs-flang-man` to generate `flang.1`. Fixes llvm#141757
Due to that, the myst_parser was explictly imported. Adding Placeholder .md files which are required by index.md
copy-flang-src-docs builds Source/ directory and in fixing, did not include it in the HTML target deps
ae70eed
to
b94047e
Compare
Thanks for the review, @kiranchandramohan. Whenever @tarunprabhu and @pawosm-arm, I request someone with commit access to merge the PR, I do not have the access. |
I'm in two minds here. I've tried this PR after forced push, yet nothing really has changed from my previous comment (there's still this The true benefit of this commit is that the building process continues even with |
By the warning, you mean inside the contents of the man page right? Not the build process giving warning to nonexistent documents. |
Something to consider: maybe we should introduce the use of something like this? https://github.com/cpuguy83/go-md2man |
Yes, as I quoted it above:
|
Ok, I see your point. I think a follow up PR to iron out the contents of the man page should be the course of action since the issue this fix links to is for the build process only. The changes might get too convoluted; what do you think? |
This seems somewhat simpler: https://kristaps.bsd.lv/lowdown |
From the other side, the manpage flang-doc generates from markdown demonstrates that we are able to make markdown to manpage conversion without engaging any external tools. What we lack is an input which could establish the correct structure, something that clang has (see https://github.com/llvm/llvm-project/blob/main/clang/docs/CommandGuide/clang.rst) but in the markdown format. I'd rather see this PR introducing a stub for such content rather than generating a substantial in size content made of something which isn't a manpage. |
Sounds good. |
I am not very familiar with the way the manpage for clang is generated. Does clang.rst have to be manually kept up to date with any command line options that are added? As far as a stub goes, does it make sense to write a barebones |
To be clear, the generated Flang Manual Page (In Progreess)
This man page is under development.
For full documentation, please visit [Flang's Online Command Line Reference](https://flang.llvm.org/docs/FlangCommandLineReference.html) Does this proposal have consensus? |
This patch refactors the Flang documentation CMake and Sphinx configuration to address build issues.
CMake changes:
gen_rst_file_from_td()
call out of the HTML-only block so that bothdocs-flang-html
anddocs-flang-man
builds depend on the generatedFlangCommandLineReference.rst
file.copy-flang-src-docs
target so that both HTML and man builds use the preparedSource/
directory.docs-flang-man
target explicitly depends on thegen-FlangCommandLineReference.rst
generation andthe
copy-flang-src-docs
directory preparation.conf.py changes:
myst_parser
dependency as a required Markdown parser for both HTML and man builds.flang(1)
man page.Fixes #141757