Styling improvements and use shell in doc

Signed-off-by: Jorge Marques <jorge.marques@analog.com>
analogdevicesinc · Oct 25, 2024 · 6c50810 · 6c50810
1 parent 3156a79
commit 6c50810
Show file tree

Hide file tree

Showing 6 changed files with 66 additions and 78 deletions.
diff --git 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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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 <https://github.com/pypa/setuptools/issues/3269>`_
@@ -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