Topics

How to use tables in add-on help documents


rowen brian
 

We know that readme is markdown syntax.
I want to use the table in the help document, but the built document does not present the table.

Test sample:


| Cell One | Cell Two |
| ---- | ---- |
| Cell Three | Cell Four |


James Scholes
 

Tables are not supported by basic/original Markdown, only by extended versions e.g. the GitHub flavour. The fact that your table isn't being rendered suggests that an appropriate extensions isn't enabled within the pipeline being used to convert your documentation into HTML. I'd suggest either:

1. filing an issue at https://github.com/nvdaaddons/AddonTemplate, assuming you're using the template; or
2. just using an HTML table.

Regards,

James Scholes

On 10/01/2021 at 7:23 pm, rowen brian wrote:
We know that readme is markdown syntax.
I want to use the table in the help document, but the built document does not present the table.

Test sample:


| Cell One | Cell Two |
| ---- | ---- |
| Cell Three | Cell Four |


rowen brian
 

Hi  James,

Thank you very much for your answers, I will submit a Issue to the add-on template.
Thanks.


Sean
 

no need to issue.

The markdown package installed with pip supports gfm (github flavored markdown).
You can update your sconsstruct.

On 11/01/2021 10:27, rowen brian wrote:
Hi  James,

Thank you very much for your answers, I will submit a Issue to the add-on template.
Thanks.


James Scholes
 

The sconstruct file can be updated for an individual add-on, sure. But at that point, you're modifying the template, which may introduce conflicts when the template is updated in the future. It seems a good idea for the template to support additional Markdown extensions for everyone who uses it.

Regards,

James Scholes

On 11/01/2021 at 5:20 am, Sean wrote:
no need to issue.

The markdown package installed with pip supports gfm (github flavored markdown).
You can update your sconsstruct.

On 11/01/2021 10:27, rowen brian wrote:
Hi  James,

Thank you very much for your answers, I will submit a Issue to the add-on template.
Thanks.


 

Hi all,
In fact, what James proposes is exactly the route to be taken now - expect a change to Add-on Template. This will be divided into two stages:
1. Version 2020.4: tables extension will be hard-coded and will be enabled to address an immediate concern. This will involve editing SConstruct.
2. Version 2021.1: a new build vars list (named markdownExtensions) will be introduced to let you specify Markdown extensions to be used for your docs. This will require editing both SConstruct and build vars for individual add-ons.

I'm doing this in two stages as it is too late to introduce large changes to build vars as Add-on Template 2020.4 is about to be published, and because the first stage is optional (only needed if you must include tables in your readme). Delaying the second stage to a later time also allows us to think about possible implications of moving to a new Python version and dependencies. I will also be editing the requirements statements to point out that Markdown 3.3 or later should be used.
For those who can't wait to try Add-on Template 2021.1, keep an eye on commits to add-on template repo as I'll be committing stage 2 after NVDA 2020.4 is released to the general public.
Cheers,
Joseph

-----Original Message-----
From: nvda-devel@groups.io <nvda-devel@groups.io> On Behalf Of James Scholes
Sent: Monday, January 11, 2021 10:45 AM
To: nvda-devel@groups.io
Subject: Re: [nvda-devel] How to use tables in add-on help documents

The sconstruct file can be updated for an individual add-on, sure. But at that point, you're modifying the template, which may introduce conflicts when the template is updated in the future. It seems a good idea for the template to support additional Markdown extensions for everyone who uses it.

Regards,

James Scholes

On 11/01/2021 at 5:20 am, Sean wrote:
no need to issue.

The markdown package installed with pip supports gfm (github flavored markdown).
You can update your sconsstruct.

On 11/01/2021 10:27, rowen brian wrote:
Hi James,

Thank you very much for your answers, I will submit a Issue to the add-on template.
Thanks.