Mixing
Documenting CMakeLists.txt and custom or local .cmake files
What are good ways to document my project CMakeLists.txt files and local project .cmake files? There is a two year old question/answer Documenting CMake scripts that I am essentially asking here again. The answer contains the statement
Currently, CMake 3.0 is under development which will get a new documentation system based on Sphinx and reStructuredText. I guess that this will bring new ways to document your modules.
I have looked at the cmake developer documentation, but this new documentation system seems geared towards the documentation of cmake itself. I do not see how I can use this to document my user-defined project CMakeLists.txt files or local .cmake files.
I am hoping that since the cmake project internally has various sphinx directives and roles that there is was some way as a user I could take advantage of this internal usage of sphinx. I would like to be able to have some markup in my CMakeLists.txt files and local .cmake files without having to reinvent the wheel. There are related efforts in other projects. For example the ROS catkin project seems to offer the most complete approach that I have seen, but that is fairly heavyweight not easy to use for non-ROS projects. (As an example, look at their extracted cmake api page.) The simplest, is the sphinx-contrib cmakedomain, but that relies on a separate rst source doc rather than an autodoc approach with markup comments.
Perhaps this is a question for the cmake list, but I was hoping someone was monitoring StackOverflow.
cmake documentation python-sphinx
edited May 23 '17 at 11:45
Community♦
11
asked Apr 5 '16 at 0:44
PhilPhil
3,0751642
add a comment |
What are good ways to document my project CMakeLists.txt files and local project .cmake files? There is a two year old question/answer Documenting CMake scripts that I am essentially asking here again. The answer contains the statement
Currently, CMake 3.0 is under development which will get a new documentation system based on Sphinx and reStructuredText. I guess that this will bring new ways to document your modules.
I have looked at the cmake developer documentation, but this new documentation system seems geared towards the documentation of cmake itself. I do not see how I can use this to document my user-defined project CMakeLists.txt files or local .cmake files.
I am hoping that since the cmake project internally has various sphinx directives and roles that there is was some way as a user I could take advantage of this internal usage of sphinx. I would like to be able to have some markup in my CMakeLists.txt files and local .cmake files without having to reinvent the wheel. There are related efforts in other projects. For example the ROS catkin project seems to offer the most complete approach that I have seen, but that is fairly heavyweight not easy to use for non-ROS projects. (As an example, look at their extracted cmake api page.) The simplest, is the sphinx-contrib cmakedomain, but that relies on a separate rst source doc rather than an autodoc approach with markup comments.
Perhaps this is a question for the cmake list, but I was hoping someone was monitoring StackOverflow.
cmake documentation python-sphinx
edited May 23 '17 at 11:45
Community♦
11
asked Apr 5 '16 at 0:44
PhilPhil
3,0751642
I don't think this is related to CMake, is about sphinix itself. Did you try reading a tutorial about it usage?
– Joel
Apr 5 '16 at 1:45
Yes, I know how to use sphinx. But I do not know how to use the cmake 3 new documentation system to document myCMakeLists.txtor other.cmakefiles. The cmake documentation system seems to be for documenting cmake not for users to document their project specific cmake files.
– Phil
Apr 5 '16 at 2:31
add a comment |
What are good ways to document my project CMakeLists.txt files and local project .cmake files? There is a two year old question/answer Documenting CMake scripts that I am essentially asking here again. The answer contains the statement
Currently, CMake 3.0 is under development which will get a new documentation system based on Sphinx and reStructuredText. I guess that this will bring new ways to document your modules.
I have looked at the cmake developer documentation, but this new documentation system seems geared towards the documentation of cmake itself. I do not see how I can use this to document my user-defined project CMakeLists.txt files or local .cmake files.
I am hoping that since the cmake project internally has various sphinx directives and roles that there is was some way as a user I could take advantage of this internal usage of sphinx. I would like to be able to have some markup in my CMakeLists.txt files and local .cmake files without having to reinvent the wheel. There are related efforts in other projects. For example the ROS catkin project seems to offer the most complete approach that I have seen, but that is fairly heavyweight not easy to use for non-ROS projects. (As an example, look at their extracted cmake api page.) The simplest, is the sphinx-contrib cmakedomain, but that relies on a separate rst source doc rather than an autodoc approach with markup comments.
Perhaps this is a question for the cmake list, but I was hoping someone was monitoring StackOverflow.
cmake documentation python-sphinx
edited May 23 '17 at 11:45
Community♦
11
asked Apr 5 '16 at 0:44
PhilPhil
3,0751642
What are good ways to document my project CMakeLists.txt files and local project .cmake files? There is a two year old question/answer Documenting CMake scripts that I am essentially asking here again. The answer contains the statement
Currently, CMake 3.0 is under development which will get a new documentation system based on Sphinx and reStructuredText. I guess that this will bring new ways to document your modules.
I have looked at the cmake developer documentation, but this new documentation system seems geared towards the documentation of cmake itself. I do not see how I can use this to document my user-defined project CMakeLists.txt files or local .cmake files.
I am hoping that since the cmake project internally has various sphinx directives and roles that there is was some way as a user I could take advantage of this internal usage of sphinx. I would like to be able to have some markup in my CMakeLists.txt files and local .cmake files without having to reinvent the wheel. There are related efforts in other projects. For example the ROS catkin project seems to offer the most complete approach that I have seen, but that is fairly heavyweight not easy to use for non-ROS projects. (As an example, look at their extracted cmake api page.) The simplest, is the sphinx-contrib cmakedomain, but that relies on a separate rst source doc rather than an autodoc approach with markup comments.
Perhaps this is a question for the cmake list, but I was hoping someone was monitoring StackOverflow.
cmake documentation python-sphinx
cmake documentation python-sphinx
edited May 23 '17 at 11:45
Community♦
11
asked Apr 5 '16 at 0:44
PhilPhil
3,0751642
edited May 23 '17 at 11:45
Community♦
11
asked Apr 5 '16 at 0:44
PhilPhil
3,0751642
edited May 23 '17 at 11:45
Community♦
11
edited May 23 '17 at 11:45
Community♦
11
edited May 23 '17 at 11:45
Community♦
11
11
asked Apr 5 '16 at 0:44
PhilPhil
3,0751642
asked Apr 5 '16 at 0:44
PhilPhil
3,0751642
asked Apr 5 '16 at 0:44
PhilPhil
3,0751642
3,0751642
I don't think this is related to CMake, is about sphinix itself. Did you try reading a tutorial about it usage?
– Joel
Apr 5 '16 at 1:45
Yes, I know how to use sphinx. But I do not know how to use the cmake 3 new documentation system to document myCMakeLists.txtor other.cmakefiles. The cmake documentation system seems to be for documenting cmake not for users to document their project specific cmake files.
– Phil
Apr 5 '16 at 2:31
add a comment |
I don't think this is related to CMake, is about sphinix itself. Did you try reading a tutorial about it usage?
– Joel
Apr 5 '16 at 1:45
Yes, I know how to use sphinx. But I do not know how to use the cmake 3 new documentation system to document myCMakeLists.txtor other.cmakefiles. The cmake documentation system seems to be for documenting cmake not for users to document their project specific cmake files.
– Phil
Apr 5 '16 at 2:31
I don't think this is related to CMake, is about sphinix itself. Did you try reading a tutorial about it usage?
– Joel
Apr 5 '16 at 1:45
I don't think this is related to CMake, is about sphinix itself. Did you try reading a tutorial about it usage?
– Joel
Apr 5 '16 at 1:45
Yes, I know how to use sphinx. But I do not know how to use the cmake 3 new documentation system to document my
CMakeLists.txt or other .cmake files. The cmake documentation system seems to be for documenting cmake not for users to document their project specific cmake files.– Phil
Apr 5 '16 at 2:31
Yes, I know how to use sphinx. But I do not know how to use the cmake 3 new documentation system to document my
CMakeLists.txt or other .cmake files. The cmake documentation system seems to be for documenting cmake not for users to document their project specific cmake files.– Phil
Apr 5 '16 at 2:31
add a comment |
1 Answer
1
active
oldest
votes
Despite the quote, I don't think the Sphinx-related code from CMake is useful for users. I made the same experience like you, my project's CMake did not match well with the Sphinx code used in the CMake documentation.
Just use plain Sphinx and create your own templates.
answered Apr 5 '16 at 6:38
usr1234567usr1234567
10.4k75390
I was hoping that since the cmake project internally has various sphinx directives and roles that there was some way as a user I could take advantage of them without having to reinvent the wheel. I will add this clarification to my question.
– Phil
Apr 5 '16 at 16:09
@Phil: Sure, I understood your question that way. And for my project, this did not work out. Unfortunately.
– usr1234567
Apr 5 '16 at 19:18
add a comment |
Your Answer
StackExchange.ifUsing("editor", function () {
StackExchange.using("externalEditor", function () {
StackExchange.using("snippets", function () {
StackExchange.snippets.init();
});
});
}, "code-snippets");
StackExchange.ready(function() {
var channelOptions = {
tags: "".split(" "),
id: "1"
};
initTagRenderer("".split(" "), "".split(" "), channelOptions);
StackExchange.using("externalEditor", function() {
// Have to fire editor after snippets, if snippets enabled
if (StackExchange.settings.snippets.snippetsEnabled) {
StackExchange.using("snippets", function() {
createEditor();
});
}
else {
createEditor();
}
});
function createEditor() {
StackExchange.prepareEditor({
heartbeatType: 'answer',
autoActivateHeartbeat: false,
convertImagesToLinks: true,
noModals: true,
showLowRepImageUploadWarning: true,
reputationToPostImages: 10,
bindNavPrevention: true,
postfix: "",
imageUploader: {
brandingHtml: "Powered by u003ca class="icon-imgur-white" href="https://imgur.com/"u003eu003c/au003e",
contentPolicyHtml: "User contributions licensed under u003ca href="https://creativecommons.org/licenses/by-sa/3.0/"u003ecc by-sa 3.0 with attribution requiredu003c/au003e u003ca href="https://stackoverflow.com/legal/content-policy"u003e(content policy)u003c/au003e",
allowUrls: true
},
onDemand: true,
discardSelector: ".discard-answer"
,immediatelyShowMarkdownHelp:true
});
}
});
Sign up or log in
StackExchange.ready(function () {
StackExchange.helpers.onClickDraftSave('#login-link');
});
Sign up using Google
Sign up using Facebook
Sign up using Email and Password
Post as a guest
Required, but never shown
StackExchange.ready(
function () {
StackExchange.openid.initPostLogin('.new-post-login', 'https%3a%2f%2fstackoverflow.com%2fquestions%2f36415261%2fdocumenting-cmakelists-txt-and-custom-or-local-cmake-files%23new-answer', 'question_page');
}
);
Post as a guest
Required, but never shown
1 Answer
1
active
oldest
votes
1 Answer
1
active
oldest
votes
active
oldest
votes
active
oldest
votes
Despite the quote, I don't think the Sphinx-related code from CMake is useful for users. I made the same experience like you, my project's CMake did not match well with the Sphinx code used in the CMake documentation.
Just use plain Sphinx and create your own templates.
answered Apr 5 '16 at 6:38
usr1234567usr1234567
10.4k75390
I was hoping that since the cmake project internally has various sphinx directives and roles that there was some way as a user I could take advantage of them without having to reinvent the wheel. I will add this clarification to my question.
– Phil
Apr 5 '16 at 16:09
@Phil: Sure, I understood your question that way. And for my project, this did not work out. Unfortunately.
– usr1234567
Apr 5 '16 at 19:18
add a comment |
Despite the quote, I don't think the Sphinx-related code from CMake is useful for users. I made the same experience like you, my project's CMake did not match well with the Sphinx code used in the CMake documentation.
Just use plain Sphinx and create your own templates.
answered Apr 5 '16 at 6:38
usr1234567usr1234567
10.4k75390
I was hoping that since the cmake project internally has various sphinx directives and roles that there was some way as a user I could take advantage of them without having to reinvent the wheel. I will add this clarification to my question.
– Phil
Apr 5 '16 at 16:09
@Phil: Sure, I understood your question that way. And for my project, this did not work out. Unfortunately.
– usr1234567
Apr 5 '16 at 19:18
add a comment |
Despite the quote, I don't think the Sphinx-related code from CMake is useful for users. I made the same experience like you, my project's CMake did not match well with the Sphinx code used in the CMake documentation.
Just use plain Sphinx and create your own templates.
answered Apr 5 '16 at 6:38
usr1234567usr1234567
10.4k75390
Despite the quote, I don't think the Sphinx-related code from CMake is useful for users. I made the same experience like you, my project's CMake did not match well with the Sphinx code used in the CMake documentation.
Just use plain Sphinx and create your own templates.
answered Apr 5 '16 at 6:38
usr1234567usr1234567
10.4k75390
answered Apr 5 '16 at 6:38
usr1234567usr1234567
10.4k75390
answered Apr 5 '16 at 6:38
usr1234567usr1234567
10.4k75390
answered Apr 5 '16 at 6:38
usr1234567usr1234567
10.4k75390
10.4k75390
I was hoping that since the cmake project internally has various sphinx directives and roles that there was some way as a user I could take advantage of them without having to reinvent the wheel. I will add this clarification to my question.
– Phil
Apr 5 '16 at 16:09
@Phil: Sure, I understood your question that way. And for my project, this did not work out. Unfortunately.
– usr1234567
Apr 5 '16 at 19:18
add a comment |
I was hoping that since the cmake project internally has various sphinx directives and roles that there was some way as a user I could take advantage of them without having to reinvent the wheel. I will add this clarification to my question.
– Phil
Apr 5 '16 at 16:09
@Phil: Sure, I understood your question that way. And for my project, this did not work out. Unfortunately.
– usr1234567
Apr 5 '16 at 19:18
I was hoping that since the cmake project internally has various sphinx directives and roles that there was some way as a user I could take advantage of them without having to reinvent the wheel. I will add this clarification to my question.
– Phil
Apr 5 '16 at 16:09
I was hoping that since the cmake project internally has various sphinx directives and roles that there was some way as a user I could take advantage of them without having to reinvent the wheel. I will add this clarification to my question.
– Phil
Apr 5 '16 at 16:09
@Phil: Sure, I understood your question that way. And for my project, this did not work out. Unfortunately.
– usr1234567
Apr 5 '16 at 19:18
@Phil: Sure, I understood your question that way. And for my project, this did not work out. Unfortunately.
– usr1234567
Apr 5 '16 at 19:18
add a comment |
Thanks for contributing an answer to Stack Overflow!
- Please be sure to answer the question. Provide details and share your research!
But avoid …
- Asking for help, clarification, or responding to other answers.
- Making statements based on opinion; back them up with references or personal experience.
To learn more, see our tips on writing great answers.
Sign up or log in
StackExchange.ready(function () {
StackExchange.helpers.onClickDraftSave('#login-link');
});
Sign up using Google
Sign up using Facebook
Sign up using Email and Password
Post as a guest
Required, but never shown
StackExchange.ready(
function () {
StackExchange.openid.initPostLogin('.new-post-login', 'https%3a%2f%2fstackoverflow.com%2fquestions%2f36415261%2fdocumenting-cmakelists-txt-and-custom-or-local-cmake-files%23new-answer', 'question_page');
}
);
Post as a guest
Required, but never shown
Sign up or log in
StackExchange.ready(function () {
StackExchange.helpers.onClickDraftSave('#login-link');
});
Sign up using Google
Sign up using Facebook
Sign up using Email and Password
Post as a guest
Required, but never shown
Sign up or log in
StackExchange.ready(function () {
StackExchange.helpers.onClickDraftSave('#login-link');
});
Sign up using Google
Sign up using Facebook
Sign up using Email and Password
Post as a guest
Required, but never shown
Sign up or log in
StackExchange.ready(function () {
StackExchange.helpers.onClickDraftSave('#login-link');
});
Sign up using Google
Sign up using Facebook
Sign up using Email and Password
Sign up using Google
Sign up using Facebook
Sign up using Email and Password
Post as a guest
Required, but never shown
Required, but never shown
Required, but never shown
Required, but never shown
Required, but never shown
Required, but never shown
Required, but never shown
Required, but never shown
Required, but never shown
I don't think this is related to CMake, is about sphinix itself. Did you try reading a tutorial about it usage?
– Joel
Apr 5 '16 at 1:45
Yes, I know how to use sphinx. But I do not know how to use the cmake 3 new documentation system to document my
CMakeLists.txtor other.cmakefiles. The cmake documentation system seems to be for documenting cmake not for users to document their project specific cmake files.– Phil
Apr 5 '16 at 2:31