Extract documentation to its own CMakeLists.txt#37
Extract documentation to its own CMakeLists.txt#37ekohl wants to merge 1 commit intoteddych:masterfrom
Conversation
This is still incomplete and doesn't quite work, but it shows the concept. The idea is that documentation building is contained to the Documentation directory. If pandoc is present, it builds the documentation unconditionally.
ekohl
force-pushed
the
extract-docs-cmake
branch
from
fb56ad0 to
47cfd39
Compare
| @@ -0,0 +1,156 @@ | |||
| cmake_minimum_required(VERSION 3.18) | |||
There was a problem hiding this comment.
Note this is 3.18 (unlike 3.10 in main) because find_program uses REQUIRED
| DEPENDS doc | ||
| ) | ||
|
|
||
| add_custom_command(TARGET doc-for-web POST_BUILD |
There was a problem hiding this comment.
I haven't had a good look at how to convert this, if needed at all.
There was a problem hiding this comment.
@ekohl doc-for-web creates a directory structure that is intended to replace the current documentation on the railcontrol.org web server, i.e., Teddy needs it.
No other target should depend on doc-for-web, but for transparency and keeping things together please keep it.
| install(DIRECTORY ${OUTPUT_HTML}/ DESTINATION ${CMAKE_INSTALL_DOCDIR}) | ||
|
|
||
| set(OUTPUT_CHUNKEDHTML ${CMAKE_CURRENT_BINARY_DIR}/chunkedhtml) | ||
| file(MAKE_DIRECTORY ${OUTPUT_CHUNKEDHTML}) |
There was a problem hiding this comment.
This probably needs to be an install like above for regular docs, if we want to have this in the file install.
There was a problem hiding this comment.
@ekohl the "chunked html" documentation doesn't need to be installed as of today, but likely in the future. No other target should depend on it, yet.
The generated HTML documentation is intended to be integrated into the web interface, e.g., adding a 'Help' button to the switch configuration dialog window.
| file(COPY ${DOCDATA} DESTINATION ${OUTPUT_HTML}) | ||
| file(COPY ${DOCDATA} DESTINATION ${OUTPUT_CHUNKEDHTML}) | ||
|
|
||
| # German |
There was a problem hiding this comment.
Given the repetition I've been wondering if a macro could be written to iterate over every language, but that's a potential future optimization.
There was a problem hiding this comment.
I consider it still an acceptable amount of repetition at the moment.
| file(GLOB DOCDATA_DE de/*.png) | ||
| file(COPY ${DOCDATA_DE} DESTINATION ${OUTPUT_HTML_DE}) | ||
|
|
||
| file(GLOB DOC_DE de/*.md) |
There was a problem hiding this comment.
Please don't GLOB but keep the manual listing of markdown files for every language. The order matters and reflects the order of sections of documents pandoc produces.
There was a problem hiding this comment.
That is something I wasn't sure about. Thanks for confirming my suspicion.
|
I am not very familiar with cmake, therefore I am happy if you think about and improve everything around the documentation! |
|
And what fuddl already mentioned: The plan is to replace the existing documentation on the web with the pandoc generated chunked output. So the idea is that the output has the same directory structure and the same filenames as what is now on the railcontrol.org site. |
Honestly, I didn't know cmake at all until I started to look at railcontrol and I've just been reading documentation. |
3 participants
This is still incomplete and doesn't quite work, but it shows the concept.
The idea is that documentation building is contained to the Documentation directory. If pandoc is present, it builds the documentation unconditionally.
It's an alternative to #36.