From c33da3fb7800044dd1c9742147011671679281cb Mon Sep 17 00:00:00 2001 From: Tim Hagen Date: Fri, 27 Sep 2024 12:21:34 +0200 Subject: [PATCH] updated documentation and deleted some unused files --- application/Dockerfile.application | 25 ------ application/src/tira_nginx.conf | 59 ------------- application/src/uwsgi.ini | 11 --- application/src/uwsgi_params | 17 ---- documentation/conf.py | 57 ++++++------ documentation/development/changelog.rst | 12 ++- documentation/development/devenvironment.rst | 2 +- documentation/development/documentation.rst | 4 +- .../development/specification/index.rst | 4 +- .../{restapi.rst => restapi/guidelines.rst} | 3 - .../specification/restapi/index.rst | 12 +++ .../specification/technology/index.rst | 5 +- documentation/organizers/intro.rst | 1 + documentation/participants/participate.rst | 2 + documentation/sphinxext/openapi.py | 88 +++++++++++++++++++ model/src/log/errors/.gitkeep | 0 model/src/log/virtual-machine-hosts/.gitkeep | 0 model/src/log/virtual-machines/.gitkeep | 0 18 files changed, 151 insertions(+), 151 deletions(-) delete mode 100644 application/Dockerfile.application delete mode 100644 application/src/tira_nginx.conf delete mode 100644 application/src/uwsgi.ini delete mode 100644 application/src/uwsgi_params rename documentation/development/specification/{restapi.rst => restapi/guidelines.rst} (99%) create mode 100644 documentation/development/specification/restapi/index.rst create mode 100644 documentation/sphinxext/openapi.py delete mode 100644 model/src/log/errors/.gitkeep delete mode 100644 model/src/log/virtual-machine-hosts/.gitkeep delete mode 100644 model/src/log/virtual-machines/.gitkeep diff --git a/application/Dockerfile.application b/application/Dockerfile.application deleted file mode 100644 index d0140e093..000000000 --- a/application/Dockerfile.application +++ /dev/null @@ -1,25 +0,0 @@ -# Only change in case of new / updated dependencies -FROM webis/tira-application:basis-0.0.96 - -# This Dockerfile ensures that all dependencies do rarely change by starting from a basis image -# that contains already all dependencies (so that the minor versions do rarely change, but we -# still have the most recent version if we build everything from time to time from scratch). -# If you Add new dependencies, please install the base image from scratch with build-docker-basis -COPY application /tira/application - -WORKDIR /tira/application/src - -ENV HF_HOME=/mnt/ceph/tira/data/publicly-shared-datasets/huggingface/ - -RUN cd /tira/application/src && \ - chown tira:tira -R /tira/application && \ - python3 manage.py collectstatic && \ - chmod +x /tira/application/src/tira/endpoints/aha && \ - cp /tira/application/src/tira/management/commands/irds_cli.sh /irds_cli.sh && \ - rm -f ./config/settings.yml ./config/config.yml ./config/tira-application-config.dev.yml && \ - -RUN cd /tira/application/ && \ - ./test/run_all_tests.sh - -CMD sh -c "nginx && uwsgi --uid 1010 --gid 1010 --ini /tira/application/src/uwsgi.ini" - diff --git a/application/src/tira_nginx.conf b/application/src/tira_nginx.conf deleted file mode 100644 index 5a9fd3752..000000000 --- a/application/src/tira_nginx.conf +++ /dev/null @@ -1,59 +0,0 @@ -user tira tira; ## Default: nobody -worker_processes 50; ## Default: 1 -error_log logs/error.log; -pid logs/nginx.pid; -worker_rlimit_nofile 8192; - -events { - worker_connections 4096; ## Default: 1024 -} - -http { - include mime.types; - include /etc/nginx/fastcgi.conf; - - default_type application/octet-stream; - log_format main '$remote_addr - $remote_user [$time_local] $status ' - '"$request" $body_bytes_sent "$http_referer" ' - '"$http_user_agent" "$http_x_forwarded_for"'; - access_log logs/access.log main; - sendfile on; - tcp_nopush on; - server_names_hash_bucket_size 128; # this seems to be required for some vhosts - - upstream django { - server unix:///tira/application/tira.sock; # for a file socket -# server 127.0.0.1:8001; # for a web port socket (we'll use this first) - } - - # configuration of the server - server { - # the port your site will be served on - listen 80; - # the domain name it will serve for - server_name tira.io; # substitute your machine's IP address or FQDN - charset utf-8; - - - # max upload size - client_max_body_size 75M; # adjust to taste - - # Django media - location /media { - alias /var/www/media; # your Django project's media files - amend as required - } - - location /public { - alias /var/www/public; # your Django project's static files - amend as required - } - - # Finally, send all non-media requests to the Django server. - location / { - uwsgi_pass django; - include /tira/application/src/uwsgi_params; # the uwsgi_params file you installed - uwsgi_ignore_client_abort on; - uwsgi_read_timeout 360; - } - } -} - diff --git a/application/src/uwsgi.ini b/application/src/uwsgi.ini deleted file mode 100644 index bfec5f419..000000000 --- a/application/src/uwsgi.ini +++ /dev/null @@ -1,11 +0,0 @@ -[uwsgi] -strict = true -master = true -enable-threads = true -chdir = /tira/application/src -module = django_admin.wsgi:application -processes = 50 -pidfile = /tmp/project-master.pid -socket = /tira/application/tira.sock -vacuum = true -max-requests = 5000 \ No newline at end of file diff --git a/application/src/uwsgi_params b/application/src/uwsgi_params deleted file mode 100644 index e42d9a910..000000000 --- a/application/src/uwsgi_params +++ /dev/null @@ -1,17 +0,0 @@ - -uwsgi_param QUERY_STRING $query_string; -uwsgi_param REQUEST_METHOD $request_method; -uwsgi_param CONTENT_TYPE $content_type; -uwsgi_param CONTENT_LENGTH $content_length; - -uwsgi_param REQUEST_URI $request_uri; -uwsgi_param PATH_INFO $document_uri; -uwsgi_param DOCUMENT_ROOT $document_root; -uwsgi_param SERVER_PROTOCOL $server_protocol; -uwsgi_param REQUEST_SCHEME $scheme; -uwsgi_param HTTPS $https if_not_empty; - -uwsgi_param REMOTE_ADDR $remote_addr; -uwsgi_param REMOTE_PORT $remote_port; -uwsgi_param SERVER_PORT $server_port; -uwsgi_param SERVER_NAME $server_name; \ No newline at end of file diff --git a/documentation/conf.py b/documentation/conf.py index 270d00305..6d3566a48 100644 --- a/documentation/conf.py +++ b/documentation/conf.py @@ -12,14 +12,16 @@ # import os import sys -sys.path.insert(0, os.path.abspath('../')) + +sys.path.insert(0, os.path.abspath("./sphinxext")) +sys.path.insert(0, os.path.abspath("../")) # -- Project information ----------------------------------------------------- -project = 'TIRA' -copyright = '2024, Webis' -author = 'Webis' +project = "TIRA" +copyright = "2024, Webis" +author = "Webis" # -- General configuration --------------------------------------------------- @@ -28,32 +30,33 @@ # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom # ones. extensions = [ - 'sphinx.ext.autodoc', - 'sphinx.ext.todo', - 'sphinx.ext.doctest', - 'sphinx.ext.viewcode', - 'sphinx_design', - 'sphinxcontrib.plantuml', - 'sphinxcontrib.umlet', - 'myst_parser', + "sphinx.ext.autodoc", + "sphinx.ext.todo", + "sphinx.ext.doctest", + "sphinx.ext.viewcode", + "sphinx_design", + "sphinxcontrib.plantuml", + "sphinxcontrib.umlet", + "myst_parser", + "openapi", ] -todo_include_todos=True -python_display_short_literal_types=True -python_use_unqualified_type_names=True -viewcode_line_numbers=True +todo_include_todos = True +python_display_short_literal_types = True +python_use_unqualified_type_names = True +viewcode_line_numbers = True -doctest_global_setup = ''' +doctest_global_setup = """ from tira.io_utils import * -''' +""" # Add any paths that contain templates here, relative to this directory. -templates_path = ['_templates'] +templates_path = ["_templates"] # List of patterns, relative to source directory, that match files and # directories to ignore when looking for source files. # This pattern also affects html_static_path and html_extra_path. -exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store'] +exclude_patterns = ["_build", "Thumbs.db", ".DS_Store"] # -- Options for HTML output ------------------------------------------------- @@ -61,9 +64,9 @@ # The theme to use for HTML and HTML Help pages. See the documentation for # a list of builtin themes. # -html_theme = 'furo' -html_title = 'TIRA' -language = 'en' +html_theme = "furo" +html_title = "TIRA" +language = "en" html_logo = "https://assets.tira.io/tira-icons/tira-logo.svg" html_theme_options: Dict[str, Any] = { @@ -87,15 +90,15 @@ } -plantuml_output_format = 'svg_img' +plantuml_output_format = "svg_img" umlet_binary_path = "/usr/share/umlet/Umlet/umlet.sh" # Add any paths that contain custom static files (such as style sheets) here, # relative to this directory. They are copied after the builtin static files, # so a file named "default.css" will overwrite the builtin "default.css". -html_static_path = ['_static'] +html_static_path = ["_static"] html_css_files = [ - 'custom.css', -] \ No newline at end of file + "custom.css", +] diff --git a/documentation/development/changelog.rst b/documentation/development/changelog.rst index 59309f4cc..ffe8c88aa 100644 --- a/documentation/development/changelog.rst +++ b/documentation/development/changelog.rst @@ -18,6 +18,12 @@ Removed -Alpha ------ -- Initial release + + + + +0.0.136 +------- +For more information, we refer to the `Release Page `_. + +- First Release using the Release Pipeline diff --git a/documentation/development/devenvironment.rst b/documentation/development/devenvironment.rst index e3b827ec9..3f4f43f24 100644 --- a/documentation/development/devenvironment.rst +++ b/documentation/development/devenvironment.rst @@ -87,7 +87,7 @@ The development environment is quite similar to the production environment and c .. umlet-figure:: images/devenv.uxf Lookup Tables for Useful Information ------------------------------------ +------------------------------------ Root Password ~~~~~~~~~~~~~ You may occasionally need root privileges in the development container. The password for the root user is ``1234`` (if diff --git a/documentation/development/documentation.rst b/documentation/development/documentation.rst index 013e86f23..7c3ec8a44 100644 --- a/documentation/development/documentation.rst +++ b/documentation/development/documentation.rst @@ -1,5 +1,5 @@ -Documentation -============= +Adding Documentation +==================== General ------- All files relevant to TIRA's documentation can be found in the `documentation` subdirectory of the diff --git a/documentation/development/specification/index.rst b/documentation/development/specification/index.rst index 4f4284992..fc5405809 100644 --- a/documentation/development/specification/index.rst +++ b/documentation/development/specification/index.rst @@ -14,7 +14,7 @@ Specification :link-type: doc .. grid-item-card:: :octicon:`broadcast` REST API - :link: restapi + :link: restapi/index :link-type: doc .. grid-item-card:: :octicon:`plug` Technology @@ -28,5 +28,5 @@ Specification userstories architecture - restapi + restapi/index technology/index diff --git a/documentation/development/specification/restapi.rst b/documentation/development/specification/restapi/guidelines.rst similarity index 99% rename from documentation/development/specification/restapi.rst rename to documentation/development/specification/restapi/guidelines.rst index bc0478b45..8537a318d 100644 --- a/documentation/development/specification/restapi.rst +++ b/documentation/development/specification/restapi/guidelines.rst @@ -1,6 +1,3 @@ -REST-API -=================== - Guidelines ---------- diff --git a/documentation/development/specification/restapi/index.rst b/documentation/development/specification/restapi/index.rst new file mode 100644 index 000000000..dff3274cd --- /dev/null +++ b/documentation/development/specification/restapi/index.rst @@ -0,0 +1,12 @@ +REST-API +======== + +.. toctree:: + :maxdepth: 2 + :glob: + :hidden: + + * + +.. include-openapi:: ./development/specification/rest-api.yml + :filter-tags: v1 diff --git a/documentation/development/specification/technology/index.rst b/documentation/development/specification/technology/index.rst index fc2e715b1..89148ef94 100644 --- a/documentation/development/specification/technology/index.rst +++ b/documentation/development/specification/technology/index.rst @@ -10,4 +10,7 @@ Technology Other Resources --------------- -* `Semantic Versioning `_ \ No newline at end of file +* `Semantic Versioning `_ +* :RFC:`3986` -- URI Syntax (esp. Section 3) +* :RFC:`4395` -- Registration Guidelines for new URI Schemes +* :RFC:`8615` -- ``/.well-known`` URIs diff --git a/documentation/organizers/intro.rst b/documentation/organizers/intro.rst index e3061d8be..218503e24 100644 --- a/documentation/organizers/intro.rst +++ b/documentation/organizers/intro.rst @@ -59,4 +59,5 @@ How do I... .. _orgfaq: .. rubric:: Frequently Asked Questions + No questions yet :material-regular:`mood;1.5em;sd-text-success`. diff --git a/documentation/participants/participate.rst b/documentation/participants/participate.rst index b63cd797a..85d2222de 100644 --- a/documentation/participants/participate.rst +++ b/documentation/participants/participate.rst @@ -8,6 +8,7 @@ Participating in a Shared Task .. _JoinTask: + Joining a Task and preparing your Environment --------------------------------------------- @@ -59,6 +60,7 @@ out more): .. _SubmitSubmission: + Submitting your Submission -------------------------- At this point, you came up with a brilliant idea and would like to submit it to TIRA for evaluation and to take pride in diff --git a/documentation/sphinxext/openapi.py b/documentation/sphinxext/openapi.py new file mode 100644 index 000000000..7e7363e25 --- /dev/null +++ b/documentation/sphinxext/openapi.py @@ -0,0 +1,88 @@ +import docutils.nodes as nodes +import yaml +from docutils.parsers.rst import directives +from docutils.statemachine import StringList +from sphinx.application import Sphinx +from sphinx.util.docutils import SphinxDirective + +_endpoint_format = """\ +.. dropdown:: :bdg-primary:`{verb}` {name} + :color: {color} + + {summary} + {description} +""" + + +class IncludeOpenAPI(SphinxDirective): + has_content = False + required_arguments = 1 + optional_arguments = 0 + final_argument_whitespace = False + option_spec = {"filter-tags": directives.unchanged} + + def run(self): + source = directives.uri(self.arguments[0]) + with open(source, "r") as f: + data = yaml.safe_load(f) + return [ + node + for name, path in data["paths"].items() + for node in self.render_path(name, path) + ] + + def render_path(self, name: str, path: dict) -> list[nodes.Node]: + return [ + node + for verb, ep in path.items() + if verb + in ( + "delete", + "connect", + "get", + "head", + "options", + "patch", + "post", + "put", + "trace", + ) + for node in self.render_endpoint(name, verb, ep) + ] + + def render_endpoint(self, name: str, verb: str, endpoint: dict) -> list[nodes.Node]: + include = ( + len( + set(endpoint.get("tags", [])).intersection( + self.options["filter-tags"].split(",") + ) + ) + > 0 + ) + if not include: + return [] + color = { + "get": "dark", + "patch": "warning", + "delete": "danger", + "put": "secondary", + }.get(verb, "muted") + para: nodes.Element = nodes.paragraph(translatable=False) + self.state.nested_parse( + StringList( + _endpoint_format.format( + name=name, + verb=verb.upper(), + color=color, + description=endpoint.get("description", ""), + summary=endpoint.get("summary", ""), + ).splitlines() + ), + 0, + para, + ) + return [para] + + +def setup(sphinx: Sphinx): + sphinx.add_directive("include-openapi", IncludeOpenAPI) diff --git a/model/src/log/errors/.gitkeep b/model/src/log/errors/.gitkeep deleted file mode 100644 index e69de29bb..000000000 diff --git a/model/src/log/virtual-machine-hosts/.gitkeep b/model/src/log/virtual-machine-hosts/.gitkeep deleted file mode 100644 index e69de29bb..000000000 diff --git a/model/src/log/virtual-machines/.gitkeep b/model/src/log/virtual-machines/.gitkeep deleted file mode 100644 index e69de29bb..000000000