docs: Initial docs structure and infrastructure #1272
Conversation
Thank you for contributing to the Leapp project!Please note that every PR needs to comply with the Leapp Guidelines and must pass all tests in order to be mergeable.
Packit will automatically schedule regression tests for this PR's build and latest upstream leapp build.
Note that first time contributors cannot run tests automatically - they need to be started by a reviewer. It is possible to schedule specific on-demand tests as well. Currently 2 test sets are supported,
See other labels for particular jobs defined in the Please open ticket in case you experience technical problem with the CI. (RH internal only) Note: In case there are problems with tests not being triggered automatically on new PR/commit or pending for a long time, please contact leapp-infra. |
matejmatuska
force-pushed
the
introduce-docs
branch
from
77f498d to
b2bacdd
Compare
matejmatuska
force-pushed
the
introduce-docs
branch
2 times, most recently
from
fae4837 to
96ef2e8
Compare
| help: | ||
| @source venv/bin/activate && \ | ||
| $(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) | ||
| livehtml: |
There was a problem hiding this comment.
| livehtml: | |
| livehtml: html |
this will automatically build html without the need to think about it
matejmatuska
force-pushed
the
introduce-docs
branch
from
1e9015a to
c0493e2
Compare
pirat89
force-pushed
the
introduce-docs
branch
from
1bb4148 to
1e4fa59
Compare
NOTE: sphinx-autodoc is NOT included, because the way it works is by importing python modules, which are (apart from commands) not used in this repository, therefore it doesn't work.
Add documentation entry describing some common guidelines and best practices. Undoubtedly, some tips might be missing, but we have to start somewhere.
Add docs describing how to write actors that are user-configurable using the functionality provided by leapp framework. Declaration of repository-global and actor-local configuration is described, followed by information on how to consume user-provided config values. Finally, we describe how a user can supply actors with configuration values.
Add docs that cover mostly scratch container and how are its mounts set up. The docs are missing the following topics: - how are repositories set up - why does the actor deals with broken symlinks
Previously all changed files have been checked by (given to) isort. However the documentation files under `docs/` diretory should be ignored. Let's skip them.
* Update references to libraries and functions to use the full module id * Added note about followed code guidelines regarding leapp python guidelines * Mention explicitly that interaction with a system is prohibited during the ChecksPhase phase * Mentions the testutils library in tips for testing * Update section about the python compatibility to cover all requirements for compatibility instead of Py2/3 only * Note explicitly the subprocess library is forbidden in the leapp repositories * Extend information about requirements & good practices on PR description, and commit messages * Add tip that people should omit work in main branch
The file is needed for RTD and also the doc Makefile is trying to search information from the file about the needed / required python version.
pirat89
force-pushed
the
introduce-docs
branch
from
660ccf9 to
2ef491a
Compare
NOTE: sphinx-autodoc is NOT included, because the way it works is by importing python modules, which are (apart from commands) not used in this repository, therefore it doesn't work.
In the future we could use sphinx-autoapi (https://sphinx-autoapi.readthedocs.io/en/latest/) which autogenerates docs by actually parsing source code. From my testing it will work with some tweaks.
TODO: