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.