Closed HGpunktT closed 4 weeks ago
This is expected behavior. I do not commit HTML documentation to the repository (thus reflected in the source archive you linked to), only the markdown files. GitHub automatically generates HTML from markdown for the website, and HTML documentation is generated for the release archives: https://github.com/orbitalquark/textadept/blob/3fe3ad4836c469c2a30233a244bb297659d8f672/.github/workflows/release.yml#L93-L99.
If you wish to generate the documentation after compiling the application yourself, you can run the same commands (or just copy over the HTML files from a release/nightly archive).
I suggest to include the mentioned code snippet in the cmake processing. So no additional HTML files will be in the source repository and everyone compiling the application will create the HTML files to have them available for the help function.
That is a fine suggestion, but I'm not familiar enough with CMake to add a non-required target that generates HTML documentation. That is, I don't want the documentation generated as part of the build process, and if that fails, then the entire build fails. This is because HTML documentation generation has two external dependencies: Lua and Markdown and users may not have those on their systems (nor does Textadept depend on either of them).
Ideally there would be the usual cmake --build build_dir
step to build the Textadept executable, and then something like cmake --build build_dir --target docs
to build the HTML documentation as a separate, optional step. Although now that I think about it, there's also cmake --install
, which bundles everything together. Should documentation already exist? Or can it be generated after? How will the documentation's existence or non-existence affect cmake --install
? It's getting complicated very quickly.
Generation of the HTML files could be controlled by a cmake
option, say HTML_DOC=ON|OFF
, that can be defaulted to OFF.
lua
and markdown
are only build dependencies, that means they are only needed during the build process (like cmake)
and would not become dependencies of Textadept
.
As long as no cmake
expert can help with an appropriate modification of CMakeLists.txt
files, I shall follow your suggestion and transfer the HTML files from https://orbitalquark.github.io/textadept/ when building a package for a Linux distribution.
When installing or uninstalling such a package, the package manager of that distribution has to take care whether documentation already exists or not.
That's a good idea. I hadn't thought of that. I'll look into it. Thanks!
There are no HTML files (except index.html) in the source archive https://github.com/orbitalquark/textadept/archive/refs/tags/textadept_12.4.tar.gz but these are required to implement the help function in a customary compiled application.