analogdevicesinc / precision-converters-firmware

Precision Converters Embedded Firmware Repository
https://analogdevicesinc.github.io/precision-converters-firmware/
Apache License 2.0
15 stars 17 forks source link

Use Doctools #54

Closed gastmaier closed 7 months ago

gastmaier commented 7 months ago

Changed to be merged to sphinx-web-documentation

CLAassistant commented 7 months ago

CLA assistant check
All committers have signed the CLA.

gastmaier commented 7 months ago

Also note that the Documentation/Update gh pages CI is running for PRs, I recommend removing on: pull_request from the ci file. Or having different targets (e.g, on pull_request build the doc but do not push to gh_pages branch)

gastmaier commented 7 months ago
  1. identifying_virtual_serial_port.png doesn't exist in the repo and the problem existed before this commit; at d10867e7ab1da2fc8eca00689aeeda90caf867ba doc:Adding doc for ad777x_iio and nanodac_console:

    /mnt/wsl/data/repos/precision-converters-firmware/doc/sphinx/source/hardware/comm_interface.rst:: WARNING: image file not readable: source/hardware/identifying_virtual_serial_port.png
  2. Same as above

  3. There is an issue with the nesting/includes across the doc: The part pages start with:

    ADXXXX IIO Application
    ------------------------

    Then the sections header are:

    ==========
    Placeholder Text
    ==========

    And finally the included page starts with

    
    =======
    Build Guide
    =======

Build Prerequisites

That means, `ADXXXX IIO Application` and `Build Prerequisites` are in the same header level ([H1](https://www.w3schools.com/tags/tag_hn.asp)), causing the odd behavior. 

Sphinx sets the header level by first appearance, for example, if `~~~~~~~` appears first, it takes the H1 position.

A quick fix is to change the *_iio.rst header to:

ADXXXX IIO Application

Setting `==` as the H1 level, still not perfect, since the other sections should be `---` instead of `===` to take the H2 level.
Other solution is to change to:

ADXXXX IIO Application """"""""""""""""""""""""""""""

Now, the `"""` takes H1 position, `===` H2, `---` H3, and so on, and searching recursively, `"""` is never used in this doc.

doc/sphinx$ grep -rn '"""' .