Dev Docs

Development Container

OooDev has a development container that can be used to develop and test code. The container is pre-configured with all the necessary tools to develop and test code. This development container is best suited for use with Vs Code.

In the development container it is possible to run LibreOffice in Gui mode (tested on Ubuntu 22.04) or in headless mode Running LibreOffice in headless mode also will work in a GitHub Codespace, even in the web browser.

When developing using the development container it is not needed to install LibreOffice on the host machine. Also, no need to set up virtual environment.

Note: The development container isolates the .venv folder from the host machine. This is done to prevent conflicts with the host machine in the event the host machine has a virtual environment set up.

Virtual Environment

Setting up virtual environment is not needed when running as a development container.

It is assumed https://github.com/Amourspirit/python_ooo_dev_tools has been cloned or unzipped to a folder.

poetry is required to install this project in a development environment.

OooDev uses a virtual environment for development purposes.

Linux

$ python -m venv ./.venv

Activate virtual environment.

source ./.venv/bin/activate

Install requirements using Poetry.

(.venv) $ poetry install

In order to run test it is essential that uno.py and unohelper.py can be imported. These files are part of the LibreOffice installation. The location of these files vary depending on OS and other factors.

On Linux what is required to communicate with LibreOffice API it a copy of, or link to uno.py and unohelper.py in the virtual environment. uno.py sets up the necessary code that makes importing from LibreOffice API possible.

OooDev has a command to accomplish this in the virtual environment on Linux.

(.venv) $ oooenv cmd-link --add

After virtual environment is set up and activated, running the above command on Linux will search in known paths for uno.py and unohelper.py and create links to files in the current virtual environment. That’s it! Now should be ready for development.

For other options try:

(.venv) $ oooenv cmd-link -h

Windows

Windows is a little trickery. Creating a link to uno.py and importing it will not work as it does in Linux. This is due to the how LibreOffice implements the python environment on Windows.

The recommended way to is to start by creating a virtual environment using a python version that matches the LibreOffice version being target. For instance LibreOffice 7.3 uses Python 3.10.

Most likely the version of Python active on your system is not going to match the LibreOffice version.

Checking LibreOffice Python version

PS C:\>"C:\Program Files\LibreOffice\program\python.exe" --version
Python 3.8.10

The details of installing a python version for use with a virtual environment is beyond the scope of this document. However, for windows I would recommend a tool such as pyenv-win.

Install command might look something link:

Lets assume Python 3.8.10 is installed to C:\Users\user\.pyenv\pyenv-win\versions\3.8.10

The recommended tool for creating the virtual environments that work with OooDev is Virtualenv.

In summary, pyenv-win installs python versions and Virtualenv creates virtual environments.

Start by using terminal to create a .venv environment in the projects root folder

PS C:\python_ooo_dev_tools> virtualenv -p "C:\Users\user\.pyenv\pyenv-win\versions\3.8.10\python.exe" .venv

Activate Virtual environment.

PS C:\python_ooo_dev_tools> .\.venv\Scripts\activate.ps1

Install requirements using poetry.

(.venv) PS C:\python_ooo_dev_tools> poetry install

After installing using the previous command it time to set the environment to work with LibreOffice.

(.venv) PS C:\python_ooo_dev_tools> oooenv env -t

This will set the virtual environment to work with LibreOffice.

To check of the virtual environment is set for LibreOffice use the following command.

(.venv) PS C:\python_ooo_dev_tools> oooenv env -u
UNO Environment

Newer versions of poetry will not work with the configuration set up for LibreOffice.

When you need to use poetry just toggle environment.

“””

(.venv) PS C:\python_ooo_dev_tools> oooenv env -t

This will toggle between the original setup configuration and the LibreOffice configuration.

Testing Virtual Environment

For a quick test of environment import uno If there is no import error you should be good to go.

PS C:\python_ooo_dev_tools> .\.venv\scripts\activate
(.venv) PS C:\python_ooo_dev_tools> python
Python 3.8.10 (default, Mar 23 2022, 15:43:48) [MSC v.1928 64 bit (AMD64)] on win32
Type "help", "copyright", "credits" or "license" for more information.
>>> import uno
>>>

Hooks

OooDev uses git hooks to ensure document and test are building.

Pointing git to hooks is required for actions to run.

After virtual environment for OooDev is activated, run the following one time command.

git config --local core.hooksPath .githooks/

After setting up hooks, commits and push runs their corresponding hooks before committing or pushing code to repo.

Sometimes it may be prudent to not run hooks, such as adding a text file for internal purposes. In these cases run --no--verify flag of git.

Example git --no-verify command:

git commit -n -m "rename somefile.txt to myfile.txt"

Docs

Building Docs

With virtual environment activated, open a terminal window and cd ./docs

Listing 1 Linux

(.venv) $ make html

Listing 2 Windows

PS C:\python_ooo_dev_tools\docs> make html

Viewing docs

Online Docs are available. Viewing local docs can be done by starting a local web-server.

OooDev has a script to make this easier. In a separate terminal window run:

Listing 3 Linux

(.venv) $ python cmds/run_http.py

Listing 4 Windows

PS C:\python_ooo_dev_tools> python .\cmds\run_http.py

This starts a web server on localhost. Docs can the be viewed at http://localhost:8000/docs/_build/html/index.html

Doc Style

Doc for project are in the ./docs folder. Docs follow a basic style guide. If you are making any changes to docs please consult the ./docs/sytle_guide.txt for guidelines.

Doc Spelling

Manual spell check

Documents are spelled checked before commit by default when Hooks are set up.

Manual spell check can be run in a ./docs terminal Windows.

(.venv) $ sphinx-build -b spelling . _build

Spelling custom dictionaries

Custom spelling dictionaries are found in ./docs/internal/dict/ directory. Any custom dictionary in this directory starting with spelling_* is auto-loaded into spellcheck.

Environment Variables

OooDev contains some environment variables.

ODEV_CONN_SOFFICE

The ConnectorBridgeBase class has a soffice parameter that can be passed to the class to specify the LibreOffice version to connect to.

Also there is a ODEV_CONN_SOFFICE environment variable can be set to specify the LO version to connect to. If soffice is passed to ConnectorBridgeBase then the soffice parameter is used; Otherwise, if ODEV_CONN_SOFFICE is set then the environment variable value is used. If neither soffice or ODEV_CONN_SOFFICE are set then the default soffice is used.

This is useful to test a LO development version.

ODEV_MACRO_LOADER_OVERRIDE

The MacroLoader context manager is used to load and reset context for macros. Sometimes it is useful to override the default MacroLoader context manager such as when testing or running macros code outside of LibreOffice. Setting the environment variable to ODEV_MACRO_LOADER_OVERRIDE=1 will override the default MacroLoader context manager and return ooodev.lo.Lo.loader_current if available.

Testing

Test are written for pytest

Warning

Make sure any unnecessary extensions are disabled in LibreOffice for testing.

For Example LanguageTool 5.8 enabled on Linux (Ubuntu 22.04) resulted in critical failure, but only when test were run in GUI mode. Disabling LanguageTool 5.8 extension resolved the testing issue.