Skip to content
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

Merged
merged 3 commits into from
Aug 8, 2023
Merged

Patch 238 darkmode #240

merged 3 commits into from
Aug 8, 2023

Conversation

ThePhisch
Copy link
Contributor

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:

  • 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.

Anton Schwarz added 2 commits August 1, 2023 15:13
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`.
@ThePhisch ThePhisch requested a review from bari12 August 1, 2023 14:52
@maany
Copy link
Member

maany commented Aug 3, 2023

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.
@ThePhisch
Copy link
Contributor Author

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 :)

done

@bari12 bari12 requested a review from maany August 8, 2023 07:57
Copy link
Member

@maany maany left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Looks good :)

@bari12 bari12 merged commit 4762b5f into rucio:main Aug 8, 2023
6 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

Successfully merging this pull request may close these issues.

3 participants