deploy: 31c5e56

useblocks · Feb 1, 2023 · 8e0640a · 8e0640a
commit 8e0640a
Show file tree

Hide file tree

Showing 513 changed files with 126,663 additions and 0 deletions.
diff --git a/.buildinfo b/.buildinfo
@@ -0,0 +1,4 @@
+# Sphinx build info version 1
+# This file hashes the configuration used when building these files. When it is not found, a full rebuild will be done.
+config: 286dd23e33d6ed5c4b6e587eb86c3b53
+tags: 645f666f9bcd5a90fca523b33c5a78b7
diff --git a/.nojekyll b/.nojekyll
diff --git a/_images/arrow-down-circle.svg b/_images/arrow-down-circle.svg
diff --git a/_images/arrow-right-circle.svg b/_images/arrow-right-circle.svg
diff --git a/_images/azuredevops-logo.png b/_images/azuredevops-logo.png
diff --git a/_images/cb_example.png b/_images/cb_example.png
diff --git a/_images/cb_json.png b/_images/cb_json.png
diff --git a/_images/cb_table.png b/_images/cb_table.png
diff --git a/_images/codebeamer-logo.png b/_images/codebeamer-logo.png
diff --git a/_images/elasticsearch-logo.png b/_images/elasticsearch-logo.png
diff --git a/_images/elasticsearch-logo.svg b/_images/elasticsearch-logo.svg
diff --git a/_images/excel_data.png b/_images/excel_data.png
diff --git a/_images/jira-logo.png b/_images/jira-logo.png
diff --git a/_images/jira_example.png b/_images/jira_example.png
diff --git a/_images/jira_table.png b/_images/jira_table.png
diff --git a/_images/sphinx-needs-card.png b/_images/sphinx-needs-card.png
diff --git a/_images/sphinx-needs-enterprise-card.png b/_images/sphinx-needs-enterprise-card.png
diff --git a/_images/sphinx-needs-enterprise-logo.png b/_images/sphinx-needs-enterprise-logo.png
diff --git a/_images/sphinx-test-reports-logo.png b/_images/sphinx-test-reports-logo.png
diff --git a/_images/sphinx_bazel_logo.png b/_images/sphinx_bazel_logo.png
diff --git a/_images/sphinx_collections_logo.png b/_images/sphinx_collections_logo.png
diff --git a/_panels_static/panels-bootstrap.5fd3999ee7762ccc51105388f4a9d115.css b/_panels_static/panels-bootstrap.5fd3999ee7762ccc51105388f4a9d115.css
diff --git a/_panels_static/panels-main.c949a650a448cc0ae9fd3441c0e17fb0.css b/_panels_static/panels-main.c949a650a448cc0ae9fd3441c0e17fb0.css
diff --git a/_panels_static/panels-variables.06eb56fa6e07937060861dad626602ad.css b/_panels_static/panels-variables.06eb56fa6e07937060861dad626602ad.css
@@ -0,0 +1,7 @@
+:root {
+--tabs-color-label-active: hsla(231, 99%, 66%, 1);
+--tabs-color-label-inactive: rgba(178, 206, 245, 0.62);
+--tabs-color-overline: rgb(207, 236, 238);
+--tabs-color-underline: rgb(207, 236, 238);
+--tabs-size-label: 1rem;
+}
diff --git a/_panels_static/panels-variables.8c0628e7e33bedb29c2dfe2857f560c3.css b/_panels_static/panels-variables.8c0628e7e33bedb29c2dfe2857f560c3.css
@@ -0,0 +1,7 @@
+:root {
+--tabs-color-label-active: rgb(42, 99, 154);
+--tabs-color-label-inactive: rgb(42, 99, 154, 0.6);
+--tabs-color-overline: rgb(42, 99, 154);
+--tabs-color-underline: rgb(42, 99, 154);
+--tabs-size-label: 0.9rem;
+}
diff --git a/_sources/api/extensions.rst.txt b/_sources/api/extensions.rst.txt
@@ -0,0 +1,10 @@
+Extensions
+===========
+
+.. contents::
+   :local:
+
+
+ServiceExtension
+----------------
+.. autoclass:: sphinx_needs_enterprise.extensions.ServiceExtension
diff --git a/_sources/api/index.rst.txt b/_sources/api/index.rst.txt
@@ -0,0 +1,8 @@
+APIs
+====
+
+
+.. toctree::
+   :maxdepth: 2
+
+   extensions
diff --git a/_sources/changelog.rst.txt b/_sources/changelog.rst.txt
@@ -0,0 +1,71 @@
+Changelog
+=========
+
+1.0.2
+-----
+**Released**: under developement
+
+1.0.1
+-----
+**Released**: 01.02.2023
+
+* Improvement: Added :ref:`cb_ssl_cert_abspath` to allow self signed certificates for codebeamer service. This uses the verify option in the `requests library <https://requests.readthedocs.io/en/latest/api/>`.
+* Improvement: Added :ref:`cb_request_delay_ms` to configure a delay between codebeamer API :ref:`cb_wiki2html` requests.
+* Improvement: Added :ref:`cb_wiki2html_id` to change the project id used when using :ref:`cb_wiki2html` 
+
+1.0.0
+-----
+**Released**: 26.09.2022
+
+* Improvement: Added needs options check for creating needs from services import.
+  `#40 <https://github.com/useblocks/sphinx-needs-enterprise/issues/40>`_
+* Improvement: Works with Sphinx-Needs ``>=1.0.1`` (only).
+
+0.1.4
+-----
+**Released**: 09.05.2022
+
+* Improvement: Support of :ref:`cb_debug` option for Codebeamer added.
+  `#25 <https://github.com/useblocks/sphinx-needs-enterprise/issues/25>`_
+* Improvement: Added config option :ref:`conf_needs_enterprise_license_warn`.
+* Bugfix: Invalid licenses do not write "warnings".
+  `#35 <https://github.com/useblocks/sphinx-needs-enterprise/issues/35>`_
+* Bugfix: Replacing ``m2r`` with ``m2r2``.
+  `#43 <https://github.com/useblocks/sphinx-needs-enterprise/issues/43>`_
+
+
+0.1.3
+-----
+**Released**: 29.11.2021
+
+* Bugfix: Fixed some hard coded versions for dependencies
+
+0.1.2
+-----
+**Released**: 29.11.2021
+
+* Improvement: :ref:`conf_raw` and :ref:`conf_wiki2html` can be set in service configuration for Codebeamer.
+* Bugfix: :ref:`cb_wiki2html` can be set to False.
+  `#27 <https://github.com/useblocks/sphinx-needs-enterprise/issues/27>`_
+* Bugfix: Not so strict dependency handling.
+
+0.1.1
+-----
+**Released**: 25.11.2021
+
+* Bugfix: Not so strict dependency handling.
+
+0.1.0
+-----
+**Released**: 25.11.2021
+
+* Improvement: Added :ref:`sne_export` for Elasticsearch.
+* Improvement: Activates parallel build support.
+  `#12 <https://github.com/useblocks/sphinx-needs-enterprise/issues/12>`_
+* Improvement: Added :ref:`Azure service <service_azure>`.
+* Improvement: Added :ref:`sne` subcommands: ``import``, ``render``, ``dev``.
+* Improvement: Added :ref:`sne`.
+* Improvement: Added :ref:`Codebeamer service <service_cb>`.
+* Improvement: Added :ref:`Jira service <service_jira>`.
+* Improvement:: Added :Ref:`cb_wiki2html` and :ref:`cb_raw` to service :ref:`service_cb`.
+  `#11 <https://github.com/useblocks/sphinx-needs-enterprise/issues/11>`_
diff --git a/_sources/contribute.rst.txt b/_sources/contribute.rst.txt
@@ -0,0 +1,147 @@
+.. _contribute:
+
+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``
+
+
+.. _contribute_docker:
+
+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: :ref:`sne_dev_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.
+
+
+
+