Contribute¶

Code linting¶

Use make format to run black on your code, which should fix most of the possible linter errors.

To run all our configured linter, run make lint.

Testing¶

As SNE is highly using external services, some tests need a running and correctly preconfigured service instance. But these service instances are not available during CI tests, so that external calls needs to be mocked.

If a test needs a running external service, e.g. to debug things easier, mark it like this:

@pytest.mark.sphinx(testroot="codebeamer")
@pytest.mark.cb_needed  # Uses marker "cb_needed"
def test_codebeamer(app):
    app.build()

New markers must be registered in pytest.ini.

Local tests should be run with pytest -m local. You can use make test-local to run all tests this way.

Currently supported are:

* ``local``: Test that can be run locally. May require external resources
* ``external_resource``: Marks tests that require external resources.
* ``cb_needed``: local tests
* ``cb_needed``: Needs a running codebeamer server.
* ``cb_docker_needed``: Needs a running docker codebeamer server.
* ``ci_test``: Marks remote tests that are executed only in GitHub workflows.
* ``sphinx``: testing sphinx.

Only tests marked with ci_test` get executed during CI runs. For local tests use make test-local, this invokes poetry run pytest -v tests -m local. Please be aware that local tests can sometimes require locally running docker containers. Local tests requiring external resources can be disabled by running make test-no-ext

So if you register a new marker, please update also the related Makefile command.

All unmarked tests must be callable without the need to use any external resources.

Sphinx support¶

How to run test cases based on a Sphinx project is nearly undocumented by Sphinx itself. Some information can be found here: https://github.com/sphinx-doc/sphinx/issues/7008

Doc build¶

With external services¶

This build is for systems, which have e.g. a running CodeBeamer instance available so that real data can be fetched during the build.

On project root: make docs-html

Under /docs: make html

Without external services / CI Build¶

If the documentation build shall act like it is performed on our used CI system (GitHub actions), the ON_CI environment variable must be set. The build will then contain images instead of trying to reach external services during the build.

On project root: make ci-docs-html

Under /docs: ON_CI=true make html

External services¶

For some services like CodeBeamer, there are open Docker Images available, which can be used to test Sphinx-Needs Enterprise and to build the documentation with active data synchronization.

To start the needed service, go to /docker/<service> and run docker-compose down && docker-compose up -d.

You can also use the sne script to start all available containers with one command for you: sne dev docker up. See: docker for details.

Codebeamer via docker¶

Open a terminal and switch folder to /docker/codebeamer.

Then run docker-compose down && docker-compose up -d.

After everything is running, open a browser with this address http://127.0.0.1:8080/.

Login data is: :username: bond :password: 007

To use the current documentation with the new codebeamer instance, you should create a project based on the agile template. In this case, some elements, like issues, get automatically created and the used filters inside this documentation should already match some of them.

Jira via docker¶

Open a terminal and switch folder to /docker/jira.

Then run docker-compose up -d.

After everything is running, open a browser with this address http://127.0.0.1:8081/.

You will be asked several questions and need to login with an atlassian cloud account to create an evaluation license for your specific server.

To test the REST API open http://127.0.0.1:8081/rest/api/2/search in a browser to get json based content, which includes all available issues.

The JIRA container should be stopped with docker-compose stop. Use stop instead of down, as down will delete the container, together with the internal config and database. So after using down you must register your server and add all the data again.

Azure DevOps¶

Azure DevOps can only be used as cloud service. A local installation is not possible. Luckily there is a free plan available, so for testing create an account via https://azure.microsoft.com/en-us/services/devops/.

For a documentation build of Sphinx-Needs Enterprise you should set the env vars NEEDS_AZURE_URL and NEEDS_AZURE_TOKEN with your specific data. They will overwrite the config set in docs/conf.py.

ElasticSearch and Kibana¶

Open a terminal and switch folder to /docker/elasticsearch.

Then run docker-compose up -d. This will start an ElasticSearch server and a Kibana server.

ElasticSearch is listening on Port 9200 and 9300. Kibana on port 5601.

To test everything, open http://127.0.0.1:5601 or http://127.0.0.1:5601/app/home#/tutorial_directory/sampleData to add some sample data.