-
Notifications
You must be signed in to change notification settings - Fork 53
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Patch 238 darkmode #240
Patch 238 darkmode #240
Conversation
Added `.devcontainer/devcontainer.json` with the definition of a docker image containing all the required packages to run and test the `tools/build_documentation.sh`-file. Simply build and connect to this dev container; mount the folder into the dev container.
Upgraded docusaurus from 2.0.1 to 2.4.1 Also added the command `serve` as a proxy for `start` because it is `npm run serve` and now you can do `yarn run start`.
Could you also update README.md with the pipeline you mentioned in the issue description? It could be helpful for the next person who jumps in to debug stuff here :) |
The pipeline for the creation of the rucio-docs for the client API is as follows: * begin process using `build_documentation.sh` * `generate_dynamic_files.sh` spins up a docker container * inside of the docker container, `generate_docs.sh` is called * which in turn calls `generate_client_api_docs.sh` * `generate_client_api_docs.sh` parses the files in `lib/rucio/client` and converts them using `pydoc-markdown`. * `pydoc-markdown` uses `rucio_processor.py` and `rucio_renderer.py` (both in `tools/run_in_docker`, which is mounted into the docker container). * "auto_generated" output markdown files' ownerships are changed * compiling this markdown into html -> completed using docusaurus as part of the github action The final stage adds styling (i.e. CSS) to the compiled markdown files. This means that in general, a dark mode can be applied. However, some components in the client api are formatted in pre-styled HTML tables (within the markdown!), these styles are never overridden. As discussed with @bari12, a simple fix to the missing dark mode is proposed here. Instead of reworking the markdown to use plain markdown-tables which are styled at the appropriate (docusaurus) step (and not HTML tables that come with their own style), we reference a docusaurus CSS variable `--ifm-background-color`, which will set the correct dark mode colour (depending on whether dark or light mode is requested). We are aware of the fact that in doing so, we reference a variable several steps before it is defined. In addition, we add even more complicated HTML/CSS syntax to markdown, which is supposed to be easy on human eyes. The benefit of this fix is that it is minimally-invasive, and that the markdown files are never supposed to be served by themselves and only act as a middle step for the entire pipeline.
06fd6cd
to
348e960
Compare
done |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Looks good :)
Also added a VS Code Devcontainer and updated dependencies
The pipeline for the creation of the rucio-docs for the client API is as
follows:
build_documentation.sh
generate_dynamic_files.sh
spins up a docker containergenerate_docs.sh
is calledgenerate_client_api_docs.sh
generate_client_api_docs.sh
parses the files inlib/rucio/client
and converts them using
pydoc-markdown
.pydoc-markdown
usesrucio_processor.py
andrucio_renderer.py
(both in
tools/run_in_docker
, which is mounted into the dockercontainer).
part of the github action
The final stage adds styling (i.e. CSS) to the compiled markdown files.
This means that in general, a dark mode can be applied. However, some
components in the client api are formatted in pre-styled HTML tables
(within the markdown!), these styles are never overridden.
As discussed with @bari12, a simple fix to the missing dark mode is
proposed here. Instead of reworking the markdown to use plain
markdown-tables which are styled at the appropriate (docusaurus) step
(and not HTML tables that come with their own style), we reference a
docusaurus CSS variable
--ifm-background-color
, which will set thecorrect dark mode colour (depending on whether dark or light mode is
requested).
We are aware of the fact that in doing so, we reference a variable
several steps before it is defined. In addition, we add even more
complicated HTML/CSS syntax to markdown, which is supposed to be easy on
human eyes. The benefit of this fix is that it is minimally-invasive,
and that the markdown files are never supposed to be served by
themselves and only act as a middle step for the entire pipeline.