gEDA Project Dox Module (`tendril.dox.gedaproject`)¶

This module generates the standard documentation set for gEDA projects.

The functions here use the tendril.dox.render module to actually produce the output files after constructing the appropriate stage.

Each document generator function in this module uses a predefined set of source files (relative to the project folder), and the output files generated by this module are put into predefined locations, with predefined names. Each function specifies the paths it operates on.

<project_doc_folder> is obtained from get_project_doc_folder()

Warning

Unless otherwise specified in the function documentation, the functions of this module will not overwrite any target output files unless the pre-existing output files are older than the source files. Note that this means the output will not be regenerated if the template is changed. You should touch one of the source files if you want to force a rebuild.

See also

tendril.dox, tendril.gedaif

Hint

The underlying functions generate the docs in the folder specified by the REFDOC_ROOT configuration option from tendril.utils.config. This folder may be configured by your instance’s instance_config.py file to point to a remote filesystem.

If you would like to generate the documentation on your local filesystem instead, you should override the instance’s REFDOC_ROOT configuration parameter by setting it to a folder on your local filesystem in your local_config_overrides.py file.

It is strongly recommended to have this folder outside of your usual project/VCS tree, in order to prevent the generated documentation (which is mostly in binary file formats) from littering your VCS working copies.

Document Set Generators

generate_docs(projfolder[, force]) Generates all the docs for a specified gEDA project.

Document Generators

`gen_confbom`(projfolder, configname[, force])	Generates a PDF of the BOM for a specified configuration of a gEDA project.
`gen_confdoc`(projfolder, configname[, force])	Generate a PDF documenting a single configuration of the project.
`gen_configsdoc`(projfolder, namebase[, force])	Generate a PDF documenting the configs of the project.
`gen_schpdf`(projfolder, namebase[, force])	Generates a PDF file of all the project schematics listed in the gEDA project file.
`gen_masterdoc`(projfolder, namebase[, force])	Generates a PDF file of the project’s Master documentation.
`gen_confpdf`(projfolder, configname, namebase)	Generates a PDF file of the documentation for a specific configuration of a project.
`gen_cobom_csv`(projfolder, namebase[, force])	Generates a CSV file in the `tendril.boms.outputbase.CompositeOutputBom` format, including the BOMs of the all the defined configurations of the project.
`gen_pcb_pdf`(projfolder[, force])	Generates a PDF file of the PCB layers for the PCB provided by the gEDA project.
`gen_pcb_gbr`(projfolder[, force])	Generates gerber files for the PCB provided by the gEDA project, and also creates a `zip` file of the generated gerbers.
`gen_pcb_dxf`(projfolder[, force])	Generates a DXF file of the PCB provided by the gEDA project.
`gen_pcb_img`(gbrfolder, outfolder, outfname)
`gen_pcbpricing`(projfolder, namebase[, force])	Generates a PDF file with the pricing of the (bare) PCB provided by the gEDA project.

Frontend Interface Functions

`get_img_list`(projfolder[, cardname])	Returns a list of `docstore.ExposedDocument` instances, pointing to the generated renders for the gEDA project or card specified by the parameters.
`get_docs_list`(projfolder[, cardname])	Returns a list of `docstore.ExposedDocument` instances, pointing to the documentation linked to the gEDA project or card specified by the parameters.

tendril.dox.gedaproject.get_project_doc_folder(projectfolder)[source]¶

tendril.dox.gedaproject.gen_confbom(projfolder, configname, force=False)[source]¶

Generates a PDF of the BOM for a specified configuration of a gEDA project.

Parameters:	projfolder (str) – The gEDA project folder configname (str) – The configuration name for which the BOM should be generated. force (bool) – Regenerate even if up-to-date.
Returns:	The output file path.

Paths

Output File : <project_doc_folder>/confdocs/<configname>-bom.pdf
Source Files : The project’s schematic folder.

Template Used

tendril/dox/templates/projects/geda-bom-simple.tex (Included version)

Stage Keys Provided

`configname`	The name of the configuration (a card or cable name).
`desc`	The description of the configuration.
`pcbname`	The name of the base PCB.
`lines`	A list of `tendril.boms.outputbase.OutputBomLine` instances

tendril.dox.gedaproject.gen_confdoc(projfolder, configname, force=False)[source]¶

Generate a PDF documenting a single configuration of the project. The document should include a reasonably thorough representation of the contents of the configuration related sections of the tendril.gedaif.conffile.ConfigsFile`.

Parameters:	projfolder (str) – The gEDA project folder configname (str) – The configuration name for which the BOM should be generated. force (bool) – Regenerate even if up-to-date.
Returns:	The output file path.

Paths

Output File : <project_doc_folder>/confdocs/<configname>-doc.pdf
Source Files : The project’s schematic folder.

Template Used

tendril/dox/templates/projects/geda-conf-doc.tex (Included version)

Stage Keys Provided

`configname`	The name of the configuration (a card or cable name).
`desc`	The description of the configuration.
`pcbname`	The name of the base PCB.
`obom`	An `tendril.boms.outputbase.OutputBom` instance

tendril.dox.gedaproject.gen_configsdoc(projfolder, namebase, force=False)[source]¶

Generate a PDF documenting the configs of the project. The document should include a reasonably thorough representation of the contents of the configuration related sections of the tendril.gedaif.conffile.ConfigsFile.

Todo

Implement this.

Parameters:	projfolder (str) – The gEDA project folder. namebase (str) – The project name. force (bool) – Regenerate even if up-to-date.
Returns:	The output file path.

Paths

Output File : <project_doc_folder>/<namebase>-configs.pdf
Source Files : The project’s schematic folder.

tendril.dox.gedaproject.gen_schpdf(projfolder, namebase, force=False)[source]¶

Generates a PDF file of all the project schematics listed in the gEDA project file. This function does not ise jinja2 and latex. It relies on tendril.gedaif.gschem.conv_gsch2pdf() instead.

Parameters:	projfolder (str) – The gEDA project folder. namebase (str) – The project name. force (bool) – Regenerate even if up-to-date.
Returns:	The output file path.

Paths

Output File : <project_doc_folder>/<namebase>-schematic.pdf
Source Files : The project’s schematic folder.

tendril.dox.gedaproject.gen_masterdoc(projfolder, namebase, force=False)[source]¶

Generates a PDF file of the project’s Master documentation. It uses other document generator functions to make the various parts of the master document and then merges them.

Note

Due to the way groups and motifs are handled, an unconfigured BOM is somewhat meaningless. Therefore, no BOM is included in the masterdoc.

Parameters:	projfolder (str) – The gEDA project folder. namebase (str) – The project name. force (bool) – Regenerate even if up-to-date.
Returns:	The output file path.

Paths

Output File : <project_doc_folder>/<namebase>-masterdoc.pdf
Source Files : The project’s schematic folder.

Included Documents

Config Documentation, generated by gen_configsdoc()
Schematic PDF, generated by gen_schpdf()

tendril.dox.gedaproject.gen_confpdf(projfolder, configname, namebase, force=False)[source]¶

Generates a PDF file of the documentation for a specific configuration of a project. It uses other document generator functions to make the various parts of the master document and then merges them.

Parameters:	projfolder (str) – The gEDA project folder. configname (str) – The name of the configuration. namebase (str) – The project name. force (bool) – Regenerate even if up-to-date.
Returns:	The output file path.

Paths

Output File : <project_doc_folder>/confdocs/<configname>.pdf
Source Files : The project’s schematic folder.

Included Documents

Configuration BOM, generated by gen_confbom()
(Full) Schematic PDF, generated by gen_schpdf()

Todo

It may be useful to rebuild the schematics after removing all the unpopulated components. This is a fairly involved process, and is deferred until later.

tendril.dox.gedaproject.gen_cobom_csv(projfolder, namebase, force=False)[source]¶

Generates a CSV file in the tendril.boms.outputbase.CompositeOutputBom format, including the BOMs of the all the defined configurations of the project. This function uses a csv.writer instead of rendering a jinja2 template.

It also generates configdocs for all the defined configurations of the project, using gen_confpdf().

Parameters:	projfolder (str) – The gEDA project folder. namebase (str) – The project name. force (bool) – Regenerate even if up-to-date.
Returns:	The output file path.

Paths

Output Files : <project_doc_folder>/confdocs/conf_boms.csv
Also triggers : gen_confpdf() for all listed configurations.
Source Files : The project’s schematic folder.

tendril.dox.gedaproject.gen_pcb_pdf(projfolder, force=False)[source]¶

Generates a PDF file of the PCB layers for the PCB provided by the gEDA project.

The pcb file is the one listed in the gEDA project file, and the pcbname is the one specified in the tendril.gedaif.conffile.ConfigsFile.

This function does not use jinja2 and latex. It relies on tendril.gedaif.pcb.conv_pcb2pdf() instead.

Parameters:	projfolder (str) – The gEDA project folder. force (bool) – Regenerate even if up-to-date.
Returns:	The output file path.

Paths

Output File : <project_doc_folder>/<pcbname>-pdf.pdf
Source Files : The project’s .pcb file.

tendril.dox.gedaproject.gen_pcb_gbr(projfolder, force=False)[source]¶

Generates gerber files for the PCB provided by the gEDA project, and also creates a zip file of the generated gerbers.

The pcbfile is the one listed in the gEDA project file, and the pcbname is the one specified in the tendril.gedaif.conffile.ConfigsFile.

This function does not use jinja2 and latex. It relies on tendril.gedaif.pcb.conv_pcb2gbr() instead.

Parameters:	projfolder (str) – The gEDA project folder. force (bool) – Regenerate even if up-to-date.
Returns:	The output file path.

Paths

Output Files : <project_doc_folder>/../gerber/*
Output Zip File : <project_doc_folder>/../<pcbfile>-gerber.zip
Source Files : The project’s .pcb file.

tendril.dox.gedaproject.gen_pcb_img(gbrfolder, outfolder, outfname, force=False)[source]¶

tendril.dox.gedaproject.gen_pcb_dxf(projfolder, force=False)[source]¶

Generates a DXF file of the PCB provided by the gEDA project.

The pcb file is the one listed in the gEDA project file, and the pcbname is the one specified in the tendril.gedaif.conffile.ConfigsFile.

This function does not use jinja2 and latex. It relies on tendril.gedaif.pcb.conv_pcb2dxf() instead.

Parameters:	projfolder (str) – The gEDA project folder. force (bool) – Regenerate even if up-to-date.
Returns:	The output file path.

Paths

Output File : <projectfolder>/pcb/<pcbfile>.dxf
Source Files : The project’s .pcb file.

tendril.dox.gedaproject.get_pcbpricing_data(projfolder)[source]¶

tendril.dox.gedaproject.gen_pcbpricing(projfolder, namebase, force=False)[source]¶

Generates a PDF file with the pricing of the (bare) PCB provided by the gEDA project.

The pcb file is the one listed in the gEDA project file, and the pcbname is the one specified in the tendril.gedaif.conffile.ConfigsFile. The pricing information is read out from the PCB’s sourcing.yaml file, which in turn is intended to be created by sourcing modules.

Todo

This function presently uses tendril.dox.render.render_lineplot(), which is marked for deprecation. It should be rewritten to use the tendril.dox.render.make_graph() route instead.

Parameters:	projfolder (str) – The gEDA project folder. namebase (str) – The project name. force (bool) – Regenerate even if up-to-date.
Returns:	The output file path.

Paths

Output File : <project_doc_folder>/<namebase>-pricing.pdf
Source Files : <projectfolder>/pcb/sourcing.yaml

tendril.dox.gedaproject.generate_docs(projfolder, force=False)[source]¶

Generates all the docs for a specified gEDA project.

Parameters:	projfolder (str) – The gEDA project folder. force (bool) – Regenerate even if up-to-date.
Returns:	The output file path.

Paths

Output File : <project_doc_folder>/confdocs/<configname>-doc.pdf
Source Files : The project’s schematic folder.

Generated Documents

Master Doc, generated by gen_masterdoc()
Cobom CSV, generated by gen_cobom_csv()
PCB PDF, generated by gen_pcb_pdf()
PCB Gerber, generated by gen_pcb_gbr()
PCB DXF, generated by gen_pcb_dxf()
PCB Pricing, generated by gen_pcbpricing()

tendril.dox.gedaproject.get_img_list(projfolder, cardname=None)[source]¶

Returns a list of docstore.ExposedDocument instances, pointing to the generated renders for the gEDA project or card specified by the parameters.

Currently, the cardname parameter is ignored, since no configuration specific images are generated.

Parameters:	projfolder – The gEDA project folder. cardname – The cardname.
Returns:	list of `ExposedDocument`

tendril.dox.gedaproject.get_docs_list(projfolder, cardname=None)[source]¶

Returns a list of docstore.ExposedDocument instances, pointing to the documentation linked to the gEDA project or card specified by the parameters.

If the cardname is not specified, the documents linked to the base PCB only are returned.

If the cardname is specified, the documents defining the specific configuration only are returned.

Parameters:	projfolder – The gEDA project folder. cardname – The cardname.
Returns:	list of `ExposedDocument`

gEDA Project Dox Module (tendril.dox.gedaproject)¶

gEDA Project Dox Module (`tendril.dox.gedaproject`)¶