Update docs content and process #999
Conversation
|
|
||
| # Sphinx and breathe require access to a Doxygen generated dir ('doxyxml') | ||
| # so we copy the whole content of the 'docs' dir to the build dir. | ||
| copytree(Path(script_dir), docs_build_path, dirs_exist_ok=True) |
There was a problem hiding this comment.
Perhaps you could set the Doxygen output directory to docs output directory instead
There was a problem hiding this comment.
I think I tested a few variants - doxygen needs specific relation to these breathe files, and also to assets and also the the include dir... it was rather compliacted for me, I just tried to describe it a little, perhaps if anyone has a better option we could improve later
| @@ -49,7 +49,9 @@ | |||
| # -- Extension configuration ------------------------------------------------- | |||
|
|
|||
| # -- Options for breathe extension ------------------------------------------- | |||
| breathe_projects = {project: "../../docs/xml"} | |||
| # 'doxyxml' dir is generated with Doxygen; it's supposed to be in a directory | |||
| # one above the config directory. | |||
There was a problem hiding this comment.
Why this relation? Can't breathe_build_directory be set explicitly to get rid of this limitation?
There was a problem hiding this comment.
don't ask me why, I think breathe expects a specific location of these files... probably could be improve somehow (I'm not breathe nor doxygen expert), but we only run this script in CI, for web page... so probaly not worth spending a lot of time
.github/workflows/docs.yml
Outdated
|
|
||
| - name: Upload artifact | ||
| uses: actions/upload-pages-artifact@0252fc4ba7626f0298f0cf00902a25c6afc77fa8 # v3.0.0 | ||
| with: | ||
| path: docs/html | ||
| path: build/docs_build/generated/html |
There was a problem hiding this comment.
If we are to stick with the build directory for generated documentation, I think that the subdirectory docs_build could be renamed to docs
There was a problem hiding this comment.
the script can be run from anywhere, so if I run this e.g. from docs dir, it would try to add a new dir docs when there's already one...
.github/workflows/docs.yml
Outdated
| mkdir build | ||
| cd build | ||
| python3 ../docs/generate_docs.py | ||
| cmake -B build -DUMF_TESTS_FAIL_ON_SKIP=ON |
There was a problem hiding this comment.
it's outdated, I think (or displayed wrong in GH)
| @@ -755,6 +755,17 @@ if(UMF_FORMAT_CODE_STYLE) | |||
| endif() | |||
| endif() | |||
|
|
|||
| find_package(Python3) | |||
| if(Python3_FOUND) | |||
There was a problem hiding this comment.
Please, check also the minimum required version.
CMakeLists.txt
Outdated
| @@ -755,6 +755,17 @@ if(UMF_FORMAT_CODE_STYLE) | |||
| endif() | |||
| endif() | |||
|
|
|||
| find_package(Python3) | |||
| if(Python3_FOUND) | |||
| message(STATUS "Adding 'docs' target") | |||
There was a problem hiding this comment.
Maybe add: (...) for creating a documentation.
docs/README.md
Outdated
| ## make docs | ||
|
|
||
| To run documentation generation via build target use CMake commands below. | ||
| To enable this target, python executable has to be found in the system. |
There was a problem hiding this comment.
with a minimum version of...
There was a problem hiding this comment.
done (don't want to duplicate the version, it's defiend below)
docs/README.md
Outdated
| ## make docs | ||
|
|
||
| To run documentation generation via build target use CMake commands below. | ||
| To enable this target, python executable has to be found in the system. |
There was a problem hiding this comment.
Add that using this target will generate docs at the build/docs_build subdir
There was a problem hiding this comment.
it's described above, no matter if run via make command or by hand - it will create the sub-dir
includes: - add missing CUDA provider in the web docs, - proxy_pool is enabled by default, move req. info to proxy_lib, - add links in README.
and update the script to work outside of scripts dir.
lukaszstolarczuk
force-pushed
the
docs-change
branch
from
89ffc02 to
c7fdc11
Compare
A few changes around docs, including:
docs, not to be a part ofscriptsdir,generate_docs.pyscript,docs,Checklist
Preview of new docs: https://lukaszstolarczuk.github.io/unified-memory-framework/introduction.html