Skip to content

eval/user-guide/transceiver: Hide template from toctree, drop old #96

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.

Sign up for GitHub

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

Open
gastmaier wants to merge 1 commit into
base: main
Choose a base branch
from
Open

eval/user-guide/transceiver: Hide template from toctree, drop old #96

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion docs/contributing/template/eval.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -6,7 +6,7 @@
developer guides, and source code.

A top-level template is available at
:git-documentation:`docs/contributing/template/example/eval.rst`
:git-documentation:`docs/solutions/reference-designs/template/_index.rst`
(:ref:`rendered <template eval>`).
Please pay attention to the comments only visible on the source code,
and remove them as you follow the template.
Expand All @@ -14,7 +14,7 @@
Base page structure
-------------------

Evaluation boards pages are divided into five main sections:

Check warning on line 17 in docs/contributing/template/eval.rst

View workflow job for this annotation

GitHub Actions / check-doc 

vale:write-good.Passive:docs/contributing/template/eval.rst:17:25 'are divided' may be passive voice. Use active voice if you can.

* Overview
* User Guide
Expand All @@ -22,7 +22,7 @@
* Developer Guide
* Help and Support

The evaluation board begins with an overview of the board, similar to the first

Check warning on line 25 in docs/contributing/template/eval.rst

View workflow job for this annotation

GitHub Actions / check-doc 

vale:write-good.TooWordy:docs/contributing/template/eval.rst:25:60 'similar to' is too wordy.
paragraph at :adi:`analog.com </>`.

The Overview section provides key points about the evaluation board to help the
Expand All @@ -45,7 +45,7 @@
:external+doctools:ref:`in-org-ref`.
Avoid using full URL paths, as they make consistency checks difficult.

Similar to the "User Guide" section, the "Developer Guide" section contains

Check warning on line 48 in docs/contributing/template/eval.rst

View workflow job for this annotation

GitHub Actions / check-doc 

vale:write-good.TooWordy:docs/contributing/template/eval.rst:48:1 'Similar to' is too wordy.
guides but aimed at developers! Here is where you can really dive deep into the
details and complex parts.
However, make sure not to duplicate content already present on other pages,
Expand All @@ -63,13 +63,13 @@
---------------------------

Some evaluation boards are simpler than others, and may not require splitting
content into subpages.

Check failure on line 66 in docs/contributing/template/eval.rst

View workflow job for this annotation

GitHub Actions / check-doc 

vale:Vale.Spelling:docs/contributing/template/eval.rst:66:14 Did you really mean 'subpages'?

If the evaluation board in question does not contain or need a developer guide,
then the "Developer Guides" section can be removed, and the "Developer Overview"

Check warning on line 69 in docs/contributing/template/eval.rst

View workflow job for this annotation

GitHub Actions / check-doc 

vale:write-good.Passive:docs/contributing/template/eval.rst:69:41 'be removed' may be passive voice. Use active voice if you can.
renamed simply to "Developers" with pointers to the source code.

Additionally, if there is only one carrier and user guide, the user guide can be

Check warning on line 72 in docs/contributing/template/eval.rst

View workflow job for this annotation

GitHub Actions / check-doc 

vale:write-good.Passive:docs/contributing/template/eval.rst:72:79 'be integrated' may be passive voice. Use active voice if you can.
integrated into the main page, replacing the carrier-agnostic paragraphs with
the carrier-specific details.

Expand All @@ -79,7 +79,7 @@
Structure Rationale
-------------------

This structure aims at minimizing content repetition, clearly defining the

Check warning on line 82 in docs/contributing/template/eval.rst

View workflow job for this annotation

GitHub Actions / check-doc 

vale:write-good.Weasel:docs/contributing/template/eval.rst:82:55 'clearly' is a weasel word!
boundaries between "Plug&Play" solutions and highly-technical developer resources,
and ensuring consistent linking to the source code and related documentation.

Expand Down
283 changes: 0 additions & 283 deletions docs/contributing/template/example/eval.rst
View file
Open in desktop

This file was deleted.

4 changes: 0 additions & 4 deletions docs/contributing/template/example/placeholder.svg
View file
Open in desktop

This file was deleted.

6 changes: 5 additions & 1 deletion ...ions/reference-designs/template/index.rst → ...ons/reference-designs/template/_index.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,4 +1,8 @@
.. _template:
:orphan:

.. Remove :orphan: marker, rename _index to index and add to a toctree

.. _template eval:

EVALUATION BOARD
===============================================================================
Expand Down Expand Up @@ -44,7 +48,7 @@
Recommendations
-------------------------------------------------------------------------------

People who follow the flow that is outlined, have a much better experience with

Check warning on line 51 in docs/solutions/reference-designs/template/_index.rst

View workflow job for this annotation

GitHub Actions / check-doc 

vale:write-good.Passive:docs/solutions/reference-designs/template/_index.rst:51:33 'is outlined' may be passive voice. Use active voice if you can.
things. However, like many things, documentation is never as complete as it
should be. If you have any questions, feel free to ask on our
:ref:`EngineerZone forums <help-and-support>`, but before that, please make
Expand All @@ -62,7 +66,7 @@
#. :ref:`Quick start guides <template quickstart>`:

#. Using the :ref:`ZCU102/Zynq UltraScale MP SoC <template quickstart zynqmp>`
#. Using the :ref:`VCK190/Versal <template quickstart versal>`

Check failure on line 69 in docs/solutions/reference-designs/template/_index.rst

View workflow job for this annotation

GitHub Actions / check-doc 

vale:Vale.Terms:docs/solutions/reference-designs/template/_index.rst:69:61 Use 'Versal' instead of 'versal'.

#. Configure an SD Card with :external+adi-kuiper-gen:doc:`Kuiper <index>`

Expand Down Expand Up @@ -91,8 +95,8 @@
- :dokuwiki:`JESD204B Transmit Linux driver <resources/tools-software/linux-drivers/jesd204/axi_jesd204_tx>`
- :dokuwiki:`JESD204B Receive Linux driver <resources/tools-software/linux-drivers/jesd204/axi_jesd204_rx>`
- :dokuwiki:`JESD204B/C AXI_ADXCVR High-speed transceivers Linux driver <resources/tools-software/linux-drivers/jesd204/axi_adxcvr>`
- :dokuwiki:`AXI ADC HDL Linux driver <resources/tools-software/linux-drivers/iio-adc/axi-adc-hdl>`

Check failure on line 98 in docs/solutions/reference-designs/template/_index.rst

View workflow job for this annotation

GitHub Actions / check-doc 

vale:Vale.Terms:docs/solutions/reference-designs/template/_index.rst:98:102 Use 'ADC(s)?' instead of 'adc'.

Check failure on line 98 in docs/solutions/reference-designs/template/_index.rst

View workflow job for this annotation

GitHub Actions / check-doc 

vale:Vale.Terms:docs/solutions/reference-designs/template/_index.rst:98:94 Use 'ADC(s)?' instead of 'adc'.
- :dokuwiki:`AXI DAC HDL Linux driver <resources/tools-software/linux-drivers/iio-dds/axi-dac-dds-hdl>`

Check failure on line 99 in docs/solutions/reference-designs/template/_index.rst

View workflow job for this annotation

GitHub Actions / check-doc 

vale:Vale.Terms:docs/solutions/reference-designs/template/_index.rst:99:102 Use 'DAC(s)?' instead of 'dac'.
- :dokuwiki:`AXI-DMAC DMA Controller Linux driver <resources/tools-software/linux-drivers/axi-dmac>`
- :dokuwiki:`CHIP1/CHIP2 Linux device driver <resources/tools-software/linux-drivers/iio-transceiver/adrv9025>`

Expand Down