A few questions


Meisam Amini <meisamamini21@...>
 

Hello.

I have just finished the NVDA add-on development guide and have a few
questions that I would really appreciate some help with.

1. How do you troubleshoot an add-on? Right now when there is a
problem with my add-on I press NVDA + f1 to open the NVDA log, and
since it doesn't have a find feature I copy the whole text, paste it
in Notepad and then search for the name of my global plugin or app
module. Is there a more elegant way of doing this?

2. Are there documentations for NVDA modules? I used git to clone the
NVDA source code and then tried to use pydoc to generate HTML
documentations for some of the modules, but encountered an error.

The help function in NVDA console is fine, but I prefer to have an
HTML or plaintext documentation if possible.

3. How the localization thing works? I wasn't able to find any
documentation showing how to do it. A glance at a few add-ons showed
me that they generally use addonHandler.initTranslation() at the
beginning of the file and then put all the strings in _() function. Is
that all? And how do you generate the template file for Poedit?

Thanks in advanced.


Noelia Ruiz
 

Hello: 1. I use the log viewer of NVDA (NVDA+f1 or from the tools menu.

2 According to the current readme of NVDA, developer documentation
cannot be built at this moment

Quote from :
https://github.com/nvaccess/nvda/
To generate the NVDA developer guide, type:
scons developerGuide
The developer guide will be placed in the devDocs folder in the output
directory. Note that the Python 3 sources of NVDA currently do not
support building NVDA developer documentation using the scons devDocs
command.

3. About translating add-ons, you can see the NVDA's developer guide:
4.4.2. Locale-specific Messages
Each language directory can also contain gettext information, which is
the system used to translate the rest of NVDA's user interface and
reported messages. As with the rest of NVDA, an nvda.mo compiled
gettext database file should be placed in the LC_MESSAGES directory
within this directory. to allow plugins in your add-on to access
gettext message information via calls to _(), you must initialize
translations at the top of each Python module by calling
addonHandler.initTranslation(). For more information about gettext and
NVDA translation in general, please read
https://github.com/nvaccess/nvda/wiki/Translating

You may create the pot file for translating add-ons locally, but if
you send add-ons to the system managed by NV Access, translators will
receive the appropriate po files and will provide translations for
your add-on if you fulfill the mentioned requirements, trat is:

1. Use Call addonHandler.initTranslation().
2. For each translatable message, use
# Translators: This is a cool message.
_("This is a translatable message")

For ease of management, we use the add-on template hosted at:

https://github.com/nvdaaddons/addontemplate

This template may require installed softwar not present in your
system. In this case (such as mine too), you may use GitHub Actions
even to build the pot file, lint your add-on on github and even create
an Nvda's log to inspect artifacts. I have worked in different
projects which require different environments and my computer is quite
old and small, so I use GitHub Actions for this. You can see
clipContentsDesigner add-on maintained by me at

https://github.com/nvdaes/clipContentsDesigner
There you will find a .github/workflows with yaml files corresponding
to GitHub actions used by me at this moment.

Hope this helps

2020-12-22 9:33 GMT+01:00, Meisam Amini <meisamamini21@gmail.com>:
Hello.

I have just finished the NVDA add-on development guide and have a few
questions that I would really appreciate some help with.

1. How do you troubleshoot an add-on? Right now when there is a
problem with my add-on I press NVDA + f1 to open the NVDA log, and
since it doesn't have a find feature I copy the whole text, paste it
in Notepad and then search for the name of my global plugin or app
module. Is there a more elegant way of doing this?

2. Are there documentations for NVDA modules? I used git to clone the
NVDA source code and then tried to use pydoc to generate HTML
documentations for some of the modules, but encountered an error.

The help function in NVDA console is fine, but I prefer to have an
HTML or plaintext documentation if possible.

3. How the localization thing works? I wasn't able to find any
documentation showing how to do it. A glance at a few add-ons showed
me that they generally use addonHandler.initTranslation() at the
beginning of the file and then put all the strings in _() function. Is
that all? And how do you generate the template file for Poedit?

Thanks in advanced.






James Scholes
 

When you open the log viewer with NVDA+F1, the cursor will automatically be placed after the most recent message but before the developer info section for the current navigator object. So if you've recently logged something from your add-on, or just encountered an error, you should be able to find it pretty quickly just by pressing Up Arrow a few times.

Of course, if you wish to use an alternative mechanism during development, you have the full power of Python at your disposal, so you could easily log to a file or something else instead. Please be sure to use the NVDA logging facilities in a released add-on, though, and note that the log viewer will be significantly more crowded if you increase NVDA's logging level.

Some NVDA modules, classes, methods and functions have documentation, but the GitHub README seems to suggest that building the docs using scons isn't officially supported at present. You can try the scons commands listed in the README, but honestly, reading the source code is easier. That's where all the documentation is pulled from anyway, so by just reading the Python code you get the both of best worlds. If something isn't documented in text, you can still read the code and experiment.

Note that some other list members have, in the past, maintained a mirror of NVDA's developer docs. I'm not sure if there is currently an up-to-date mirror available, but somebody else can chime in if so. I will say that when I was starting out with add-on development, I wished for the same thing, and tried quite a few times to build the developer docs. When I eventually gained access to them, I was completely underwhelmed and haven't used them since. The code is just easier to navigate through.

I'm not involved in localisation efforts, so someone else will also need to comment on that.

Regards,

James Scholes

On 22/12/2020 at 2:33 am, Meisam Amini wrote:
Hello.

I have just finished the NVDA add-on development guide and have a few
questions that I would really appreciate some help with.

1. How do you troubleshoot an add-on? Right now when there is a
problem with my add-on I press NVDA + f1 to open the NVDA log, and
since it doesn't have a find feature I copy the whole text, paste it
in Notepad and then search for the name of my global plugin or app
module. Is there a more elegant way of doing this?

2. Are there documentations for NVDA modules? I used git to clone the
NVDA source code and then tried to use pydoc to generate HTML
documentations for some of the modules, but encountered an error.

The help function in NVDA console is fine, but I prefer to have an
HTML or plaintext documentation if possible.

3. How the localization thing works? I wasn't able to find any
documentation showing how to do it. A glance at a few add-ons showed
me that they generally use addonHandler.initTranslation() at the
beginning of the file and then put all the strings in _() function. Is
that all? And how do you generate the template file for Poedit?

Thanks in advanced.





 

Hi,
You can use Sphinx to build documentation - looks like we need to update that part of the NVDA readme in the near future.
Cheers,
Joseph

-----Original Message-----
From: nvda-addons@nvda-addons.groups.io <nvda-addons@nvda-addons.groups.io> On Behalf Of Noelia Ruiz
Sent: Tuesday, December 22, 2020 7:47 AM
To: nvda-addons@nvda-addons.groups.io
Subject: Re: [nvda-addons] A few questions

Hello: 1. I use the log viewer of NVDA (NVDA+f1 or from the tools menu.

2 According to the current readme of NVDA, developer documentation cannot be built at this moment

Quote from :
https://github.com/nvaccess/nvda/
To generate the NVDA developer guide, type:
scons developerGuide
The developer guide will be placed in the devDocs folder in the output directory. Note that the Python 3 sources of NVDA currently do not support building NVDA developer documentation using the scons devDocs command.

3. About translating add-ons, you can see the NVDA's developer guide:
4.4.2. Locale-specific Messages
Each language directory can also contain gettext information, which is the system used to translate the rest of NVDA's user interface and reported messages. As with the rest of NVDA, an nvda.mo compiled gettext database file should be placed in the LC_MESSAGES directory within this directory. to allow plugins in your add-on to access gettext message information via calls to _(), you must initialize translations at the top of each Python module by calling addonHandler.initTranslation(). For more information about gettext and NVDA translation in general, please read https://github.com/nvaccess/nvda/wiki/Translating

You may create the pot file for translating add-ons locally, but if you send add-ons to the system managed by NV Access, translators will receive the appropriate po files and will provide translations for your add-on if you fulfill the mentioned requirements, trat is:

1. Use Call addonHandler.initTranslation().
2. For each translatable message, use
# Translators: This is a cool message.
_("This is a translatable message")

For ease of management, we use the add-on template hosted at:

https://github.com/nvdaaddons/addontemplate

This template may require installed softwar not present in your system. In this case (such as mine too), you may use GitHub Actions even to build the pot file, lint your add-on on github and even create an Nvda's log to inspect artifacts. I have worked in different projects which require different environments and my computer is quite old and small, so I use GitHub Actions for this. You can see clipContentsDesigner add-on maintained by me at

https://github.com/nvdaes/clipContentsDesigner
There you will find a .github/workflows with yaml files corresponding to GitHub actions used by me at this moment.

Hope this helps

2020-12-22 9:33 GMT+01:00, Meisam Amini <meisamamini21@gmail.com>:
Hello.

I have just finished the NVDA add-on development guide and have a few
questions that I would really appreciate some help with.

1. How do you troubleshoot an add-on? Right now when there is a
problem with my add-on I press NVDA + f1 to open the NVDA log, and
since it doesn't have a find feature I copy the whole text, paste it
in Notepad and then search for the name of my global plugin or app
module. Is there a more elegant way of doing this?

2. Are there documentations for NVDA modules? I used git to clone the
NVDA source code and then tried to use pydoc to generate HTML
documentations for some of the modules, but encountered an error.

The help function in NVDA console is fine, but I prefer to have an
HTML or plaintext documentation if possible.

3. How the localization thing works? I wasn't able to find any
documentation showing how to do it. A glance at a few add-ons showed
me that they generally use addonHandler.initTranslation() at the
beginning of the file and then put all the strings in _() function. Is
that all? And how do you generate the template file for Poedit?

Thanks in advanced.






José Manuel Delicado Alcolea
 

Hi,

In case it's useful for someone, we host a zipped copy of the developer docs on nvda.es. This is the download link for 2020.3. We update it each time a stable version is released:

https://nvda.es/wp-content/uploads/nvda_2020.3_devDocs.zip

Regards.


El 22/12/2020 a las 17:56, James Scholes escribió:
When you open the log viewer with NVDA+F1, the cursor will automatically be placed after the most recent message but before the developer info section for the current navigator object.  So if you've recently logged something from your add-on, or just encountered an error, you should be able to find it pretty quickly just by pressing Up Arrow a few times.

Of course, if you wish to use an alternative mechanism during development, you have the full power of Python at your disposal, so you could easily log to a file or something else instead.  Please be sure to use the NVDA logging facilities in a released add-on, though, and note that the log viewer will be significantly more crowded if you increase NVDA's logging level.

Some NVDA modules, classes, methods and functions have documentation, but the GitHub README seems to suggest that building the docs using scons isn't officially supported at present.  You can try the scons commands listed in the README, but honestly, reading the source code is easier.  That's where all the documentation is pulled from anyway, so by just reading the Python code you get the both of best worlds.  If something isn't documented in text, you can still read the code and experiment.

Note that some other list members have, in the past, maintained a mirror of NVDA's developer docs.  I'm not sure if there is currently an up-to-date mirror available, but somebody else can chime in if so.  I will say that when I was starting out with add-on development, I wished for the same thing, and tried quite a few times to build the developer docs.  When I eventually gained access to them, I was completely underwhelmed and haven't used them since.  The code is just easier to navigate through.

I'm not involved in localisation efforts, so someone else will also need to comment on that.

Regards,

James Scholes

On 22/12/2020 at 2:33 am, Meisam Amini wrote:
Hello.

I have just finished the NVDA add-on development guide and have a few
questions that I would really appreciate some help with.

1. How do you troubleshoot an add-on? Right now when there is a
problem with my add-on I press NVDA + f1 to open the NVDA log, and
since it doesn't have a find feature I copy the whole text, paste it
in Notepad and then search for the name of my global plugin or app
module. Is there a more elegant way of doing this?

2. Are there documentations for NVDA modules? I used git to clone the
NVDA source code and then tried to use pydoc to generate HTML
documentations for some of the modules, but encountered an error.

The help function in NVDA console is fine, but I prefer to have an
HTML or plaintext documentation if possible.

3. How the localization thing works? I wasn't able to find any
documentation showing how to do it. A glance at a few add-ons showed
me that they generally use addonHandler.initTranslation() at the
beginning of the file and then put all the strings in _() function. Is
that all? And how do you generate the template file for Poedit?

Thanks in advanced.









--

José Manuel Delicado Alcolea
Administrador y editor en la web nvda.es
Twitter: @nvda_es
Certificado en el programa NVDA Expert 2019

Logo NVDA Certified Expert


 

Hi,
I used to maintain the source code docs on my website, but with the advent of Python 3 and Sphinx, I figured it will become unnecessary to do so, as there are services that can host NVDA code docs in the future.
Cheers,
Joseph

-----Original Message-----
From: nvda-addons@nvda-addons.groups.io <nvda-addons@nvda-addons.groups.io> On Behalf Of James Scholes
Sent: Tuesday, December 22, 2020 8:56 AM
To: nvda-addons@nvda-addons.groups.io; nvda-addons <nvda-addons@groups.io>
Subject: Re: [nvda-addons] A few questions

When you open the log viewer with NVDA+F1, the cursor will automatically be placed after the most recent message but before the developer info section for the current navigator object. So if you've recently logged something from your add-on, or just encountered an error, you should be able to find it pretty quickly just by pressing Up Arrow a few times.

Of course, if you wish to use an alternative mechanism during development, you have the full power of Python at your disposal, so you could easily log to a file or something else instead. Please be sure to use the NVDA logging facilities in a released add-on, though, and note that the log viewer will be significantly more crowded if you increase NVDA's logging level.

Some NVDA modules, classes, methods and functions have documentation, but the GitHub README seems to suggest that building the docs using scons isn't officially supported at present. You can try the scons commands listed in the README, but honestly, reading the source code is easier. That's where all the documentation is pulled from anyway, so by just reading the Python code you get the both of best worlds. If something isn't documented in text, you can still read the code and experiment.

Note that some other list members have, in the past, maintained a mirror of NVDA's developer docs. I'm not sure if there is currently an up-to-date mirror available, but somebody else can chime in if so. I will say that when I was starting out with add-on development, I wished for the same thing, and tried quite a few times to build the developer docs. When I eventually gained access to them, I was completely underwhelmed and haven't used them since. The code is just easier to navigate through.

I'm not involved in localisation efforts, so someone else will also need to comment on that.

Regards,

James Scholes

On 22/12/2020 at 2:33 am, Meisam Amini wrote:
Hello.

I have just finished the NVDA add-on development guide and have a few
questions that I would really appreciate some help with.

1. How do you troubleshoot an add-on? Right now when there is a
problem with my add-on I press NVDA + f1 to open the NVDA log, and
since it doesn't have a find feature I copy the whole text, paste it
in Notepad and then search for the name of my global plugin or app
module. Is there a more elegant way of doing this?

2. Are there documentations for NVDA modules? I used git to clone the
NVDA source code and then tried to use pydoc to generate HTML
documentations for some of the modules, but encountered an error.

The help function in NVDA console is fine, but I prefer to have an
HTML or plaintext documentation if possible.

3. How the localization thing works? I wasn't able to find any
documentation showing how to do it. A glance at a few add-ons showed
me that they generally use addonHandler.initTranslation() at the
beginning of the file and then put all the strings in _() function. Is
that all? And how do you generate the template file for Poedit?

Thanks in advanced.





Meisam Amini <meisamamini21@...>
 

Thanks everyone. Very helpful information.


On Tue, Dec 22, 2020 at 8:41 PM Joseph Lee <joseph.lee22590@...> wrote:
Hi,
I used to maintain the source code docs on my website, but with the advent of Python 3 and Sphinx, I figured it will become unnecessary to do so, as there are services that can host NVDA code docs in the future.
Cheers,
Joseph

-----Original Message-----
From: nvda-addons@nvda-addons.groups.io <nvda-addons@nvda-addons.groups.io> On Behalf Of James Scholes
Sent: Tuesday, December 22, 2020 8:56 AM
To: nvda-addons@nvda-addons.groups.io; nvda-addons <nvda-addons@groups.io>
Subject: Re: [nvda-addons] A few questions

When you open the log viewer with NVDA+F1, the cursor will automatically be placed after the most recent message but before the developer info section for the current navigator object.  So if you've recently logged something from your add-on, or just encountered an error, you should be able to find it pretty quickly just by pressing Up Arrow a few times.

Of course, if you wish to use an alternative mechanism during development, you have the full power of Python at your disposal, so you could easily log to a file or something else instead.  Please be sure to use the NVDA logging facilities in a released add-on, though, and note that the log viewer will be significantly more crowded if you increase NVDA's logging level.

Some NVDA modules, classes, methods and functions have documentation, but the GitHub README seems to suggest that building the docs using scons isn't officially supported at present.  You can try the scons commands listed in the README, but honestly, reading the source code is easier.  That's where all the documentation is pulled from anyway, so by just reading the Python code you get the both of best worlds.  If something isn't documented in text, you can still read the code and experiment.

Note that some other list members have, in the past, maintained a mirror of NVDA's developer docs.  I'm not sure if there is currently an up-to-date mirror available, but somebody else can chime in if so.  I will say that when I was starting out with add-on development, I wished for the same thing, and tried quite a few times to build the developer docs.  When I eventually gained access to them, I was completely underwhelmed and haven't used them since.  The code is just easier to navigate through.

I'm not involved in localisation efforts, so someone else will also need to comment on that.

Regards,

James Scholes

On 22/12/2020 at 2:33 am, Meisam Amini wrote:
> Hello.
>
> I have just finished the NVDA add-on development guide and have a few
> questions that I would really appreciate some help with.
>
> 1. How do you troubleshoot an add-on? Right now when there is a
> problem with my add-on I press NVDA + f1 to open the NVDA log, and
> since it doesn't have a find feature I copy the whole text, paste it
> in Notepad and then search for the name of my global plugin or app
> module. Is there a more elegant way of doing this?
>
> 2. Are there documentations for NVDA modules? I used git to clone the
> NVDA source code and then tried to use pydoc to generate HTML
> documentations for some of the modules, but encountered an error.
>
> The help function in NVDA console is fine, but I prefer to have an
> HTML or plaintext documentation if possible.
>
> 3. How the localization thing works? I wasn't able to find any
> documentation showing how to do it. A glance at a few add-ons showed
> me that they generally use addonHandler.initTranslation() at the
> beginning of the file and then put all the strings in _() function. Is
> that all? And how do you generate the template file for Poedit?
>
> Thanks in advanced.
>
>
>
>
>