docs: update link roles, .gitignore

Update link roles to use the "text <link>" standard sphinx syntax.
Add __pycache__ and _build to .gitignore

Signed-off-by: Jorge Marques <jorge.marques@analog.com>
main
Jorge Marques 2023-09-06 15:00:15 -03:00 committed by Jorge Marques
parent 0597373d62
commit 468d02ea50
8 changed files with 96 additions and 61 deletions

2
.gitignore vendored
View File

@ -102,6 +102,8 @@ library/**/bd/bd.tcl
qdb qdb
tmp-clearbox tmp-clearbox
*.bin *.bin
__pycache__
_build
.qsys_edit .qsys_edit
.github/CODEOWNERS .github/CODEOWNERS
.github/PULL_REQUEST_TEMPLATE.md .github/PULL_REQUEST_TEMPLATE.md

View File

@ -172,36 +172,47 @@ have been written, which are located in the *docs/extensions* folder.
Extensions are straight forward to create, if some functionality is missing, Extensions are straight forward to create, if some functionality is missing,
consider requesting or creating one. consider requesting or creating one.
.. note::
Link-like roles use the :code:`:role:\`text <link>\`` synthax, like external
links, but without the undescore in the end.
Git role Git role
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
The Git role allows to create links to the Git repository with a shorter syntax. The Git role allows to create links to the Git repository with a shorter syntax.
The role syntax is :code:`:git-<repo>:\`<branch>:<path>\``, for example, The role syntax is :code:`:git-repo:\`text <branch:path>\``, for example:
:code:`:git-hdl:\`master:contributing/guidelines.rst\``
is rendered as :git-hdl:`master:contributing/guidelines.rst`.
You can leave the branch blank to autofill the link with the current branch.
You can also do :code:`:git-<repo>:\`/\`` for a link to the root of the * :code:`:git-hdl:\`master:docs/contributing/guidelines.rst\``
renders as :git-hdl:`master:docs/contributing/guidelines.rst`.
* :code:`:git-hdl:\`Guidelines <docs/contributing/guidelines.rst>\``
renders as :git-hdl:`Guidelines <docs/contributing/guidelines.rst>`.
The branch field is optional and will be filled with the current branch.
The text field is optional and will be filled with the file or directory name.
Finally, you can do :code:`:git-repo:\`/\`` for a link to the root of the
repository with pretty naming, for example, :code:`:git-hdl:\`/\`` is rendered repository with pretty naming, for example, :code:`:git-hdl:\`/\`` is rendered
as :git-hdl:`/`. as :git-hdl:`/`.
Part role Part role
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
The part role creates links for a part to the Analog Devices website. The part role creates links for a part to the Analog Devices Inc. website.
The role syntax is :code:`:part:\`<part_id>:<part_name>\``, for example, The role syntax is :code:`:part:\`text <part_id>\``, for example,
:code:`:part:\`ad7175-2:AD7175-2\``. :code:`:part:\`AD7175-2 <ad7175-2>\``.
Since links are case insensitive, you can also reduce it to Since links are case insensitive, you can also reduce it to
:code:`:part:\`AD7175-2\``, when *part_id* is the same as *part_name*. :code:`:part:\`AD7175-2\``, when *part_id* is the same as *text* and will render
It is rendered as :part:`AD7175-2`. as :part:`AD7175-2`.
Datasheet role Datasheet role
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
The datasheet role creates links for a datasheet in the Analog Devices website. The datasheet role creates links for a datasheet in the Analog Devices Inc. website.
The role syntax is :code:`:datasheet:\`<part_id>:<anchor>\``, for example, The role syntax is :code:`:datasheet:\`part_id:anchor\``, for example,
:code:`:datasheet:\`AD7984:[{"num"%3A51%2C"gen"%3A0}%2C{"name"%3A"XYZ"}%2C52%2C713%2C0]\`` :code:`:datasheet:\`AD7984:[{"num"%3A51%2C"gen"%3A0}%2C{"name"%3A"XYZ"}%2C52%2C713%2C0]\``
is rendered as is rendered as
:datasheet:`AD7984:[{"num"%3A51%2C"gen"%3A0}%2C{"name"%3A"XYZ"}%2C52%2C713%2C0]`. :datasheet:`AD7984:[{"num"%3A51%2C"gen"%3A0}%2C{"name"%3A"XYZ"}%2C52%2C713%2C0]`.
@ -216,29 +227,36 @@ by just copying the link in the table of contents.
Dokuwiki role Dokuwiki role
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
The dokuwiki role creates links to the Analog Devices wiki website. The dokuwiki role creates links to the Analog Devices Inc. wiki website.
The role syntax is :code:`:dokuwiki:\`<name>:<path>\``, for example, The role syntax is :code:`:dokuwiki:\`text <path>\``, for example,
:code:`:dokuwiki:\`pulsar-adc-pmods:resources/eval/user-guides/circuits-from-the-lab/pulsar-adc-pmods\`` :code:`:dokuwiki:\`pulsar-adc-pmods <resources/eval/user-guides/circuits-from-the-lab/pulsar-adc-pmods>\``
gets rendered as gets rendered as
:dokuwiki:`pulsar-adc-pmods:resources/eval/user-guides/circuits-from-the-lab/pulsar-adc-pmods`. :dokuwiki:`pulsar-adc-pmods <resources/eval/user-guides/circuits-from-the-lab/pulsar-adc-pmods>`.
EngineerZone role EngineerZone role
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
The ez role creates links to the Analog Devices EngineerZone support website. The ez role creates links to the Analog Devices Inc. EngineerZone support website.
The role syntax is :code:`:ez:\`<community>\``, for example, :code:`:ez:\`fpga\`` The role syntax is :code:`:ez:\`community\``, for example, :code:`:ez:\`fpga\``
gets rendered as :ez:`fpga`. gets rendered as :ez:`fpga`.
Xilinx role Vendor role
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
The xilinx role creates links to the Xilinx website. The vendor role creates links to the vendor's website.
The role syntax is :code:`:xilinx:\`<name>:<path>\``, for example, The role syntax is :code:`:vendor:\`text <path>\``, for example,
:code:`:xilinx:\`Zynq-7000 SoC Overview:support/documentation/data_sheets/ds190-Zynq-7000-Overview.pdf\`` :code:`:xilinx:\`Zynq-7000 SoC Overview <support/documentation/data_sheets/ds190-Zynq-7000-Overview.pdf>\``
gets rendered gets rendered
:xilinx:`Zynq-7000 SoC Overview:support/documentation/data_sheets/ds190-Zynq-7000-Overview.pdf`. :xilinx:`Zynq-7000 SoC Overview <support/documentation/data_sheets/ds190-Zynq-7000-Overview.pdf>`.
The name parameter is optional, if absent, the file name will be used as the name. The text parameter is optional, if absent, the file name will be used as the text,
for example,
:code:`:intel:\`content/www/us/en/docs/programmable/683780/22-4/general-purpose-i-o-overview.html\``
gets rendered
:intel:`content/www/us/en/docs/programmable/683780/22-4/general-purpose-i-o-overview.html`
(not very readable).
Supported vendors are: `xilinx` and `intel`.
HDL parameters directive HDL parameters directive
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

View File

@ -8,15 +8,21 @@ dft_url_ez = 'https://ez.analog.com'
dft_url_git = 'https://github.com/analogdevicesinc' dft_url_git = 'https://github.com/analogdevicesinc'
dft_url_part = 'https://www.analog.com/products' dft_url_part = 'https://www.analog.com/products'
dft_url_xilinx = 'https://www.xilinx.com' dft_url_xilinx = 'https://www.xilinx.com'
dft_url_intel = 'https://www.intel.com'
def get_url_config(name, inliner): def get_url_config(name, inliner):
app = inliner.document.settings.env.app app = inliner.document.settings.env.app
try: return getattr(app.config, "url_"+name)
if not eval("app.config.url_"+name):
raise AttributeError def get_outer_inner(text):
except AttributeError as err: """
raise ValueError(str(err)) Extract 'outer <inner>' fields.
return eval("app.config.url_"+name) """
pos = text.find('<')
if pos != -1 and text[len(text)-1] == '>':
return (text[0:pos].strip(), text[pos+1:-1])
else:
return (None, text)
def datasheet(): def datasheet():
def role(name, rawtext, text, lineno, inliner, options={}, content=[]): def role(name, rawtext, text, lineno, inliner, options={}, content=[]):
@ -32,10 +38,11 @@ def datasheet():
def dokuwiki(): def dokuwiki():
def role(name, rawtext, text, lineno, inliner, options={}, content=[]): def role(name, rawtext, text, lineno, inliner, options={}, content=[]):
path = text[text.find(':')+1:] text, path = get_outer_inner(text)
name = path[path.rfind('/')+1:] if text.find(':') in [0, -1] else text[0:text.find(':')] if text is None:
text = path[path.rfind('/')+1:]
url = get_url_config('dokuwiki', inliner) + '/' + path url = get_url_config('dokuwiki', inliner) + '/' + path
node = nodes.reference(rawtext, name, refuri=url, **options) node = nodes.reference(rawtext, text, refuri=url, **options)
return [node], [] return [node], []
return role return role
@ -58,28 +65,34 @@ def git(repo, alt_name):
name = "ADI " + alt_name + " repository" name = "ADI " + alt_name + " repository"
node = nodes.reference(rawtext, name, refuri=url, **options) node = nodes.reference(rawtext, name, refuri=url, **options)
else: else:
branch = get_active_branch_name() if text.find(':') in [0, -1] else text[0:text.find(':')] text, path = get_outer_inner(text)
path = text[text.find(':')+1:] pos = path.find(':')
branch = get_active_branch_name() if pos in [0, -1] else path[0:pos]
path = path[pos+1:]
if text is None:
text = path[path.rfind('/')+1:]
url = url + '/blob/' + branch + '/' + path url = url + '/blob/' + branch + '/' + path
node = nodes.reference(rawtext, path[path.rfind('/')+1:], refuri=url, **options) node = nodes.reference(rawtext, text, refuri=url, **options)
return [node], [] return [node], []
return role return role
def part(): def part():
def role(name, rawtext, text, lineno, inliner, options={}, content=[]): def role(name, rawtext, text, lineno, inliner, options={}, content=[]):
part_name = text[text.find(':')+1:] name, part_id = get_outer_inner(text)
part_id = part_name if text.find(':') in [0, -1] else text[0:text.find(':')] if name is None:
name = part_id
url = get_url_config('part', inliner) + '/' + part_id + '.html' url = get_url_config('part', inliner) + '/' + part_id + '.html'
node = nodes.reference(rawtext, part_name, refuri=url, **options) node = nodes.reference(rawtext, name, refuri=url, **options)
return [node], [] return [node], []
return role return role
def xilinx(): def vendor(vendor_name):
def role(name, rawtext, text, lineno, inliner, options={}, content=[]): def role(name, rawtext, text, lineno, inliner, options={}, content=[]):
name = text[text.rfind('/')+1:] if text.find(':') in [0, -1] else text[0:text.find(':')] text, path = get_outer_inner(text)
path = text[text.find(':')+1:] if text is None:
url = get_url_config('xilinx', inliner) + '/' + path text = path[path.rfind('/')+1:]
node = nodes.reference(rawtext, name, refuri=url, **options) url = get_url_config(vendor_name, inliner) + '/' + path
node = nodes.reference(rawtext, text, refuri=url, **options)
return [node], [] return [node], []
return role return role
@ -91,7 +104,8 @@ def setup(app):
app.add_role("git-testbenches", git('testbenches', "Testbenches")) app.add_role("git-testbenches", git('testbenches', "Testbenches"))
app.add_role("git-linux", git('linux', "Linux")) app.add_role("git-linux", git('linux', "Linux"))
app.add_role("part", part()) app.add_role("part", part())
app.add_role("xilinx", xilinx()) app.add_role("xilinx", vendor('xilinx'))
app.add_role("intel", vendor('intel'))
app.add_config_value('url_datasheet', dft_url_datasheet, 'env') app.add_config_value('url_datasheet', dft_url_datasheet, 'env')
app.add_config_value('url_dokuwiki', dft_url_dokuwiki, 'env') app.add_config_value('url_dokuwiki', dft_url_dokuwiki, 'env')
@ -99,6 +113,7 @@ def setup(app):
app.add_config_value('url_git', dft_url_git, 'env') app.add_config_value('url_git', dft_url_git, 'env')
app.add_config_value('url_part', dft_url_part, 'env') app.add_config_value('url_part', dft_url_part, 'env')
app.add_config_value('url_xilinx', dft_url_xilinx, 'env') app.add_config_value('url_xilinx', dft_url_xilinx, 'env')
app.add_config_value('url_intel', dft_url_intel, 'env')
return { return {
'version': '0.1', 'version': '0.1',

View File

@ -620,8 +620,8 @@ Software Support
Analog Devices recommends to use the provided software drivers. Analog Devices recommends to use the provided software drivers.
- :dokuwiki:`Analog Device AXI-DMAC DMA Controller Linux Driver: - :dokuwiki:`Analog Device AXI-DMAC DMA Controller Linux Driver
resources/tools-software/linux-drivers/axi-dmac` <resources/tools-software/linux-drivers/axi-dmac>`
Known Issues Known Issues
-------------------------------------------------------------------------------- --------------------------------------------------------------------------------

View File

@ -56,7 +56,7 @@ Interfaces
Software Software
-------------------------------------------------------------------------------- --------------------------------------------------------------------------------
* :dokuwiki:`Linux Driver:resources/tools-software/linux-drivers/spi/spi_engine`: * :dokuwiki:`Linux Driver <resources/tools-software/linux-drivers/spi/spi_engine>`:
Linux driver for the SPI Engine framework. Linux driver for the SPI Engine framework.
* :ref:`spi_engine instruction-format`: Overview of the SPI Engine Instruction * :ref:`spi_engine instruction-format`: Overview of the SPI Engine Instruction
format. format.
@ -68,25 +68,25 @@ This list contains cores that are not part of the core SPI engine framework but
make use of its interfaces and are intend to be used together with the SPI engine make use of its interfaces and are intend to be used together with the SPI engine
framework. framework.
* :dokuwiki:`util-sigma-delta-spi:resources/fpga/peripherals/util_sigma_delta_spi`: * :dokuwiki:`util-sigma-delta-spi <resources/fpga/peripherals/util_sigma_delta_spi>`:
Helper module for interfacing ADCs from the Analog Devices Sigma-Delta family. Helper module for interfacing ADCs from the Analog Devices Sigma-Delta family.
Examples Examples
-------------------------------------------------------------------------------- --------------------------------------------------------------------------------
* :dokuwiki:`CN0363:resources/eval/user-guides/eval-cn0363-pmdz`: * :dokuwiki:`CN0363 <resources/eval/user-guides/eval-cn0363-pmdz>`:
Colorimeter application using the :part:`AD7175-2` Sigma-Delta ADC. Colorimeter application using the :part:`AD7175-2` Sigma-Delta ADC.
* :dokuwiki:`resources/eval/user-guides/adaq7980-sdz`: * :dokuwiki:`resources/eval/user-guides/adaq7980-sdz`:
A 16-bit ADC subsystem with four common signal processing and conditioning blocks. A 16-bit ADC subsystem with four common signal processing and conditioning blocks.
* :dokuwiki:`resources/tools-software/uc-drivers/ad5766`: * :dokuwiki:`resources/tools-software/uc-drivers/ad5766`:
16-channel, 16-/12-bit, voltage output Digital-to-Analog Converters (DAC). 16-channel, 16-/12-bit, voltage output Digital-to-Analog Converters (DAC).
* :dokuwiki:`CN0363:resources/eval/user-guides/eval-cn0363-pmdz`: * :dokuwiki:`CN0363 <resources/eval/user-guides/eval-cn0363-pmdz>`:
The AD7768-1 is a low power, high performance, Σ-Δ analog-to-digital converter (ADC). The AD7768-1 is a low power, high performance, Σ-Δ analog-to-digital converter (ADC).
* :git-hdl:`master:projects/ad40xx_fmc` * :git-hdl:`master:projects/ad40xx_fmc`
Evaluation Board for the AD4000 Series 16-/18-/20-Bit Precision SAR ADCs. Evaluation Board for the AD4000 Series 16-/18-/20-Bit Precision SAR ADCs.
* :dokuwiki:`AD469x:resources/eval/user-guides/ad469x`: * :dokuwiki:`AD469x <resources/eval/user-guides/ad469x>`:
16-Bit, 16-Channel, 500 kSPS/1 MSPS, Easy Drive Multiplexed SAR ADC. 16-Bit, 16-Channel, 500 kSPS/1 MSPS, Easy Drive Multiplexed SAR ADC.
* :dokuwiki:`AD4630-24 / AD4030-24 / AD4630-16:resources/eval/user-guides/ad463x/hdl`: * :dokuwiki:`AD4630-24 / AD4030-24 / AD4630-16 <resources/eval/user-guides/ad463x/hdl>`:
16/24-Bit, 2 MSPS Single or Dual Channel SAR ADC. 16/24-Bit, 2 MSPS Single or Dual Channel SAR ADC.
Additional Resources Additional Resources

View File

@ -13,7 +13,7 @@ Evaluating the target device
The aim of this project is to provide support for a family of ADCs which come in The aim of this project is to provide support for a family of ADCs which come in
the form of the form of
:dokuwiki:`pulsar-adc-pmods:resources/eval/user-guides/circuits-from-the-lab/pulsar-adc-pmods`. :dokuwiki:`pulsar-adc-pmods <resources/eval/user-guides/circuits-from-the-lab/pulsar-adc-pmods>`.
They all share the same interface and the same PCB, the differences being found They all share the same interface and the same PCB, the differences being found
in their performance. The table below offers a comparison between the timing in their performance. The table below offers a comparison between the timing
parameters of the SPI interface for these devices. Using this table we can see parameters of the SPI interface for these devices. Using this table we can see
@ -67,8 +67,8 @@ SPI Engine hierarchy instantiation
-------------------------------------------------------------------------------- --------------------------------------------------------------------------------
The SPI Engine can be implemented in two ways, either by placing and connecting The SPI Engine can be implemented in two ways, either by placing and connecting
each IP individually or by using the function provided by the spi_engine.tcl each IP individually or by using the function provided by the
script :git-hdl:`master:library/spi_engine/scripts/spi_engine.tcl` :git-hdl:`master:library/spi_engine/scripts/spi_engine.tcl` script.
Using the script ensures that the correct connections are being made and that Using the script ensures that the correct connections are being made and that
the IP cores will receive the correct parameter configuration since certain the IP cores will receive the correct parameter configuration since certain
@ -264,7 +264,7 @@ Testbench
-------------------------------------------------------------------------------- --------------------------------------------------------------------------------
To check the overall performance of the design and also to expose any major To check the overall performance of the design and also to expose any major
bugs, the system can be tested using a testbench (:git-testbenches:`main:`). bugs, the system can be tested using a testbench from :git-testbenches:`/`.
The testbench framework is designed to use the same bd.tcl as the actual project The testbench framework is designed to use the same bd.tcl as the actual project
:git-testbenches:`main:pulsar_adc_pmdz/system_bd.tcl#L50` :git-testbenches:`main:pulsar_adc_pmdz/system_bd.tcl#L50`

View File

@ -35,13 +35,13 @@ Related IP Cores
This list contains cores that are not part of the core {ip name} but This list contains cores that are not part of the core {ip name} but
make use of its interfaces and are intend to be used together with the {ip name}. make use of its interfaces and are intend to be used together with the {ip name}.
* :dokuwiki:`util-sigma-delta-spi:resources/fpga/peripherals/util_sigma_delta_spi`: * :dokuwiki:`util-sigma-delta-spi <resources/fpga/peripherals/util_sigma_delta_spi>`:
Helper module for interfacing ADCs from the Analog Devices Sigma-Delta family. Helper module for interfacing ADCs from the Analog Devices Sigma-Delta family.
Examples Examples
-------------------------------------------------------------------------------- --------------------------------------------------------------------------------
* :dokuwiki:`CN0363:resources/eval/user-guides/eval-cn0363-pmdz`: * :dokuwiki:`CN0363 <resources/eval/user-guides/eval-cn0363-pmdz>`:
Colorimeter application using the :part:`AD7175-2` Sigma-Delta ADC. Colorimeter application using the :part:`AD7175-2` Sigma-Delta ADC.
Additional Resources Additional Resources

View File

@ -115,5 +115,5 @@ References
* :git-hdl:`/`, :git-hdl:`library/axi_ad777x` library. * :git-hdl:`/`, :git-hdl:`library/axi_ad777x` library.
* :git-linux:`/`. * :git-linux:`/`.
* :xilinx:`Zynq-7000 SoC Overview:support/documentation/data_sheets/ds190-Zynq-7000-Overview.pdf`. * :xilinx:`Zynq-7000 SoC Overview <support/documentation/data_sheets/ds190-Zynq-7000-Overview.pdf>`.
* :xilinx:`Zynq-7000 SoC Packaging and Pinout:support/documentation/user_guides/ug865-Zynq-7000-Pkg-Pinout.pdf`. * :xilinx:`Zynq-7000 SoC Packaging and Pinout <support/documentation/user_guides/ug865-Zynq-7000-Pkg-Pinout.pdf>`.