From 6c508105abf2fd95d821a5709b46bf0cd95770d7 Mon Sep 17 00:00:00 2001 From: Jorge Marques Date: Fri, 25 Oct 2024 18:25:55 -0300 Subject: [PATCH] Styling improvements and use shell in doc Signed-off-by: Jorge Marques --- adi_doctools/theme/cosmic/style/code.scss | 11 ----- adi_doctools/theme/cosmic/style/element.scss | 13 ------ adi_doctools/theme/cosmic/style/links.scss | 17 ++++++++ docs/ci.rst | 12 ++--- docs/cli.rst | 45 +++++++++---------- docs/install.rst | 46 ++++++++++---------- 6 files changed, 66 insertions(+), 78 deletions(-) diff --git a/adi_doctools/theme/cosmic/style/code.scss b/adi_doctools/theme/cosmic/style/code.scss index b174ebd..d68934f 100644 --- a/adi_doctools/theme/cosmic/style/code.scss +++ b/adi_doctools/theme/cosmic/style/code.scss @@ -15,13 +15,6 @@ em.sig-param, em.property { font-style: normal; } -.headerlink { - color: var(--accent-color); - opacity: 0; - transition: ease opacity .25s; - padding-left: .25em; -} - .sig-object { transition: ease background-color .25s; background-color: rgba(125, 125, 125, 0); @@ -33,10 +26,6 @@ em.sig-param, em.property { background-color: rgba(125, 125, 125, 0.1); } -.sig-object:hover .headerlink, .literal-block-wrapper:hover .headerlink { - opacity: 1; -} - .code-block-caption { text-align: center; padding-bottom: .25em; diff --git a/adi_doctools/theme/cosmic/style/element.scss b/adi_doctools/theme/cosmic/style/element.scss index 24df181..eefd7c6 100644 --- a/adi_doctools/theme/cosmic/style/element.scss +++ b/adi_doctools/theme/cosmic/style/element.scss @@ -21,19 +21,6 @@ span { scroll-margin-top: 2.5rem; } -:is(h1, h2, h3, h4, h5, h6) .headerlink, -figure .headerlink { - user-select: none; - margin-left: .25em; - opacity: 0; - transition: opacity ease .125s; -} - -:is(h1, h2, h3, h4, h5, h6):hover .headerlink, -figure:hover .headerlink { - opacity: 1; -} - code.literal { border: 1px solid rgba(125, 125, 125, 0.15); background: rgba(125, 125, 125, 0.05); diff --git a/adi_doctools/theme/cosmic/style/links.scss b/adi_doctools/theme/cosmic/style/links.scss index 2881dc7..b6873b8 100644 --- a/adi_doctools/theme/cosmic/style/links.scss +++ b/adi_doctools/theme/cosmic/style/links.scss @@ -80,3 +80,20 @@ a.icon { } } } + +/* Headerlinks */ +.headerlink { + color: var(--accent-color); + transition: opacity ease .125s; + margin-left: .25em; + user-select: none; + opacity: 0; +} + +:is(h1, h2, h3, h4, h5, h6):hover .headerlink, +.literal-block-wrapper:hover .headerlink, +.sig-object:hover .headerlink, +figure:hover .headerlink, +table:hover .headerlink { + opacity: 1; +} diff --git a/docs/ci.rst b/docs/ci.rst index 745b065..0b6abb9 100644 --- a/docs/ci.rst +++ b/docs/ci.rst @@ -88,15 +88,15 @@ documentation. To serve the build in a local server, Python built-in server can be used: -.. code:: bash +.. shell:: - python -m http.server -d /path/to/docs/_build/html + $python -m http.server -d /path/to/docs/_build/html Or with hot reload using :ref:`author-mode`: -.. code:: bash +.. shell:: - adoc author-mode -d /path/to/docs + $adoc author-mode -d /path/to/docs .. _ci-rolling-release: @@ -235,9 +235,9 @@ the target the version on the ``interref_repos`` variable, e.g. A basic ``tags.json`` can be obtained with: -.. code:: +.. shell:: - ls -d */ | cut -f1 -d'/' | jq --raw-input . | jq --slurp . > tags.json + $ls -d */ | cut -f1 -d'/' | jq --raw-input . | jq --slurp . > tags.json That means, take all directories in the root path and store as JSON. diff --git a/docs/cli.rst b/docs/cli.rst index 2e88626..05f1763 100644 --- a/docs/cli.rst +++ b/docs/cli.rst @@ -23,9 +23,9 @@ Two HTML live update strategies are available: To launch a watched instance, do: -.. code:: +.. shell:: - adoc author-mode --directory /path/to/docs + $adoc author-mode --directory /path/to/docs Where ``/path/to/docs`` is the path to the folder contain the Sphinx's ``Makefile``. @@ -34,27 +34,27 @@ sure to have Doctools as :ref:`development-install`. For PDF output, do: -.. code:: +.. shell:: - adoc author-mode --directory /path/to/docs --builder pdf + $adoc author-mode --directory /path/to/docs --builder pdf Make sure to use an PDF viewer that watches the file timestamp and automatically reloads, such as Gnome PDF (Evince). All options can be listed with: -.. code:: +.. shell:: - adoc author-mode --help + $adoc author-mode --help How can I rebuild the whole documentation within Author Mode? ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ Run ``make clean`` in another tab and then touch any file, for example: -:: +.. shell:: - make clean ; touch conf.rst + $make clean ; touch conf.rst Do **not** do ``make clean html`` since it will generate a build without the proper Author Mode environment and live reload won't work properly. @@ -85,13 +85,8 @@ Aggregate This feature is under elaboration. -Generates all documentations of the watched repositories, which currently are: - -* :git-documentation:`/` -* :git-hdl:`/` -* :git-no-os:`/` -* :git-pyadi-iio:`/` -* :git-doctools:`/` +Generates all documentations of the watched repositories +(see :git-doctools:`adi_doctools/lut.py`). Two generation strategies are available: @@ -100,9 +95,9 @@ Two generation strategies are available: For the monolithic output, do: -.. code:: +.. shell:: - adoc aggregate --directory output + $adoc aggregate --directory output Some documentations depend on auto generated sections and extra features, use the ``--extra`` option to enable those; it considers that the environment has all @@ -112,9 +107,9 @@ included, but in summary, they are just a sequence of bash commands wrapped on p For all options, do: -.. code:: +.. shell:: - adoc aggregate --help + $adoc aggregate --help HDL Render -------------------------------------------------------------------------------- @@ -125,18 +120,18 @@ It converts IP-XACT files into SVGs. To generate and open the diagram, provide the path containing the IP-XACT and use the ``--open`` option: -.. code:: +.. shell:: - adoc hdl-render --input PATH --open + $adoc hdl-render --input PATH --open For example: -.. code:: +.. shell:: - adoc hdl-render --input hdl/library/axi_dmac --open + $adoc hdl-render --input hdl/library/axi_dmac --open For all options, do: -.. code:: +.. shell:: - adoc hdl-render --help + $adoc hdl-render --help diff --git a/docs/install.rst b/docs/install.rst index 61e7d21..a606735 100644 --- a/docs/install.rst +++ b/docs/install.rst @@ -13,21 +13,21 @@ Release install Ensure pip is newer than 23.0 [#f1]_: -.. code:: +.. shell:: - pip install pip --upgrade + $pip install pip --upgrade Install the documentation tools, which will fetch this repository release: -.. code:: +.. shell:: - (cd docs ; pip install -r requirements.txt) + $(cd docs ; pip install -r requirements.txt) Test it building this documentation: -.. code:: +.. shell:: - (cd docs ; make html) + $(cd docs ; make html) .. [#f1] There is a `known bug `_ @@ -42,18 +42,18 @@ consider using a Python virtual environment (``python3-venv`` on ubuntu 22.04). To create and activate the environment, do before the previous instructions: -.. code:: +.. shell:: - python3 -m venv ./venv - source ./venv/bin/activate + $python3 -m venv ./venv + $source ./venv/bin/activate Use ``deactivate`` to exit the virtual environment. For next builds, just activate the virtual environment: -.. code:: +.. shell:: - source ./venv/bin/activate + $source ./venv/bin/activate .. _development-install: @@ -82,13 +82,13 @@ last paragraph. At the repository root, install the `npm` dependencies locally: -.. code:: +.. shell:: - npm install rollup \ - @rollup/plugin-terser \ - rollup-plugin-scss \ - sass \ - --save-dev + $npm install rollup \ + $ @rollup/plugin-terser \ + $ rollup-plugin-scss \ + $ sass \ + $ --save-dev If you choose to not use ``npm``, you can obtain pre-built web-scripts from the latest release. @@ -100,18 +100,18 @@ Fetch third-party resources Fetch third-party fonts: -.. code:: +.. shell:: - ./ci/fetch-fonts.sh + $./ci/fetch-fonts.sh Install the repository ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Finally, do a symbolic install of this repo: -.. code:: +.. shell:: - pip install -e . --upgrade + $pip install -e . --upgrade .. _removing: @@ -120,6 +120,6 @@ Removing To remove, either release or development, do: -.. code:: +.. shell:: - pip uninstall adi-doctools + $pip uninstall adi-doctools