Development
PoshPredictiveText is developed using Visual Studio. The majority of the code is C# with a small amount of PowerShell scripting to register the native argument completer and remove conda tab-expansion code, if it is installed.
Coding Standards
Coding should follow Microsoft conventions <https://docs.microsoft.com/en-us/dotnet/csharp/fundamentals/coding-style/coding-conventions>.
Additional guidance provided by Google is used where appropriate <https://google.github.io/styleguide/csharp-style.html>.
The following standards are used in the code which may conflict with the above:
var should be used sparingly and only when the type is very obvious. Use of var can make code difficult to review if the type is not clear.
Indentation is four spaces (no tabs).
Don’t use underscore to indicate private, protected, internal and protected internal fields. It adds noise.
const are indicated in capital case. Though this should change to follow Google guidelines.
Opening braces do start on a new line.
Do not use braces for single statements where it improves readability, e.g. if statements follwed by return to exit a method early if (x is null) return null;.
Testing
Testing uses Xunit, which should install from NuGet. Test coverage uses Fine Code Coverage, which is installed as an extension in Visual Studio.
Code should be covered with reasonable unit tests to validate that it works on multiple platforms.
All tests must pass before code is accepted.
PowerShell Help Documents
PowerShell has traditionally used MAML XML files for console help. These are difficult to prepare by hand. As an alternative, help files can be written in Markdown and then exported in required formats using the PowerShell PlatyPS module.
The PlatyPS module is described on GitHub <https://github.com/PowerShell/platyps>
The PlatyPS module must be downloaded and installed on the local development machine.
Install-Module -Name platyPS -Scope CurrentUser
Import-Module platyPS
The base documentation is already created within the folder PowerShellHelpDocs.
To create the external helpfiles run the following command whilist in the PowerShellHelpDocs folder.
New-ExternalHelp .\ -OutputPath en-US\
Source Code Documentation
Documentation is compiled using Sphinx to create a static website that is shared using Read The Docs. Source documents are generated using several tools and then collated within the sphinx documentation.
Source code documentation is generated by Doxygen and compiled into an XML file. This file is then parsed by Breathe/Sphinx-csharp and added to sphinx documents. All source code should be fully documented.
The PowerShell Help files are copied into the sphinx source directory and compiled into the sphinx documents.
The CHANGELOG.md is copied into the sphinx source directory and added to the sphinx documents.
Doxygen: https://doxygen.nl/index.html
Breathe: https://breathe.readthedocs.io/en/latest/index.html
Sphinx-csharp: https://github.com/rogerbarton/sphinx-csharp
Myst-parser: https://myst-parser.readthedocs.io/en/latest/
Sphinx RTD Theme: https://sphinx-rtd-theme.readthedocs.io/en/stable/
Download and install Doxygen (https://doxygen.nl/download.html). If installing on Windows, add the doxygen bin folder to the path C:Program Filesdoxygenbin.
Create a Python environment for the Sphinx tools and install packages.
conda create -n poshpredictivetext python=3.10 sphinx sphinx_rtd_theme breathe myst-parser
Install Sphinx-csharp to add c# support within Sphinx/Breathe.
pip install git+https://github.com/rogerbarton/sphinx-csharp.git
All documentation is generated during packaging and assumes that a ‘conda’ environment named poshpredictivetext is configured with the required dependencies.