Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

doc: mild doc improvements #4676

Open
wants to merge 4 commits into
base: master
Choose a base branch
from
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions doc/conf.py
Original file line number Diff line number Diff line change
Expand Up @@ -33,6 +33,7 @@
"sphinx_rtd_theme",
"sphinx.ext.extlinks",
"sphinxcontrib.openapi",
"sphinxcontrib.mermaid",
]

copybutton_prompt_text = r"\w*\$ " # matches e.g. <hostname>$
Expand Down
16 changes: 13 additions & 3 deletions doc/dev/contribute.rst
Original file line number Diff line number Diff line change
Expand Up @@ -45,6 +45,15 @@ No matter what language you want to contribute to, one of the first steps to tak
up a development environment. See :ref:`setting-up-the-development-environment` for the needed steps.
If you encounter issues, please visit our :ref:`Slack <slack>` and ask for help.

.. _code-map:

Souce code map
==============

Because the code is mostly written in Go and hosted on a public repository, its inline documentation
is rendered automatically at `<https://pkg.go.dev/github.com/scionproto/scion>`__ and includes a helpful
index.

.. _finding-an-issue-to-contribute-to:

Finding an issue to contribute to
Expand Down Expand Up @@ -93,12 +102,13 @@ implementation projects.

The current members of the TC Implementation are:

* Jean-Christophe Hugly (|span-github| `@jiceatscion <https://github.com/jiceatscion>`_, |span-slack| @Jean-Christophe Hugly)
* Dominik Roos (|span-github| `@oncilla <https://github.com/oncilla>`_, |span-slack| @roosd)
* Jean-Christophe Hugly (|span-github| `@jiceatscion <https://github.com/jiceatscion>`_, |span-slack| @jiceatscion)
* Dominik Roos (|span-github| `@oncilla <https://github.com/oncilla>`_, |span-slack| @Dominik Roos)
* François Wirz (|span-github| `@FR4NK-W <https://github.com/FR4NK-W>`_, |span-slack| @frank)
* Lukas Vogel (|span-github| `@lukedirtwalker <https://github.com/lukedirtwalker>`_, |span-slack| @luke)
* Marc Frei (|span-github| `@marcfrei <https://github.com/marcfrei>`_, |span-slack| @marcfrei)
* Jordi Subirà (|span-github| `@JordiSubira <https://github.com/JordiSubira>`_, |span-slack| @jordisubira)
* Jordi Subirà (|span-github| `@JordiSubira <https://github.com/JordiSubira>`_, |span-slack| @Jordi Subirà-Nieto)
* Markus Legner (|span-github| `@mlegner <https://github.com/mlegner>`_, |span-slack| @Markus Legner)


.. rubric:: Responsibilities and Tasks
Expand Down
3 changes: 2 additions & 1 deletion doc/requirements.in
Original file line number Diff line number Diff line change
Expand Up @@ -5,4 +5,5 @@ sphinx_design
sphinx-autobuild
sphinx-lint
sphinx-rtd-theme
sphinxcontrib-openapi
sphinxcontrib-openapi
sphinxcontrib-mermaid
25 changes: 16 additions & 9 deletions doc/requirements.txt
Original file line number Diff line number Diff line change
Expand Up @@ -310,11 +310,13 @@ pyyaml==6.0.1 \
--hash=sha256:fca0e3a251908a499833aa292323f32437106001d436eca0e6e7833256674585 \
--hash=sha256:fd1592b3fdf65fff2ad0004b5e363300ef59ced41c2e6b3a99d4089fa8c5435d \
--hash=sha256:fd66fc5d0da6d9815ba2cebeb4205f95818ff4b79c3ebe268e75d961704af52f
# via sphinxcontrib-openapi
# via
# sphinxcontrib-mermaid
# sphinxcontrib-openapi
recommonmark==0.7.1 \
--hash=sha256:1b1db69af0231efce3fa21b94ff627ea33dee7079a01dd0a7f8482c3da148b3f \
--hash=sha256:bdb4db649f2222dcd8d2d844f0006b958d627f732415d399791ee436a3686d67
# via -r requirements.in
# via -r doc/requirements.in
referencing==0.34.0 \
--hash=sha256:5773bd84ef41799a5a8ca72dc34590c041eb01bf9aa02632b4a973fb0181a844 \
--hash=sha256:d53ae300ceddd3169f1ffa9caf2cb7b769e92657e4fafb23d34b93679116dfd4
Expand Down Expand Up @@ -539,39 +541,40 @@ sphinx==7.3.7 \
--hash=sha256:413f75440be4cacf328f580b4274ada4565fb2187d696a84970c23f77b64d8c3 \
--hash=sha256:a4a7db75ed37531c05002d56ed6948d4c42f473a36f46e1382b0bd76ca9627bc
# via
# -r requirements.in
# -r doc/requirements.in
# recommonmark
# sphinx-autobuild
# sphinx-copybutton
# sphinx-design
# sphinx-rtd-theme
# sphinxcontrib-httpdomain
# sphinxcontrib-jquery
# sphinxcontrib-mermaid
# sphinxcontrib-openapi
sphinx-autobuild==2024.4.16 \
--hash=sha256:1c0ed37a1970eed197f9c5a66d65759e7c4e4cba7b5a5d77940752bf1a59f2c7 \
--hash=sha256:f2522779d30fcbf0253e09714f274ce8c608cb6ebcd67922b1c54de59faba702
# via -r requirements.in
# via -r doc/requirements.in
sphinx-copybutton==0.5.2 \
--hash=sha256:4cf17c82fb9646d1bc9ca92ac280813a3b605d8c421225fd9913154103ee1fbd \
--hash=sha256:fb543fd386d917746c9a2c50360c7905b605726b9355cd26e9974857afeae06e
# via -r requirements.in
# via -r doc/requirements.in
sphinx-design==0.6.0 \
--hash=sha256:e9bd07eecec82eb07ff72cb50fc3624e186b04f5661270bc7b62db86c7546e95 \
--hash=sha256:ec8e3c5c59fed4049b3a5a2e209360feab31829346b5f6a0c7c342b894082192
# via -r requirements.in
# via -r doc/requirements.in
sphinx-lint==0.9.1 \
--hash=sha256:185cee19ff1129549c45e15a3b25404daeb47c54d15112dda589cedad82957aa \
--hash=sha256:df34271ab65ce43676cbd90726f4dea5cd200b43b01448b2aee8f06e609edcbb
# via -r requirements.in
# via -r doc/requirements.in
sphinx-mdinclude==0.6.0 \
--hash=sha256:764b6aeee28002b9d02060758266761a2c724805594d264b19e6ceeaa3bad393 \
--hash=sha256:b1cb4dfa22ce17ca20e90e34d4349d8a97c5052709d9c4eed051cdabb615b20b
# via sphinxcontrib-openapi
sphinx-rtd-theme==2.0.0 \
--hash=sha256:bd5d7b80622406762073a04ef8fadc5f9151261563d47027de09910ce03afe6b \
--hash=sha256:ec93d0856dc280cf3aee9a4c9807c60e027c7f7b461b77aeffed682e68f0e586
# via -r requirements.in
# via -r doc/requirements.in
sphinxcontrib-applehelp==1.0.8 \
--hash=sha256:c40a4f96f3776c4393d933412053962fac2b84f4c99a7982ba42e09576a70619 \
--hash=sha256:cb61eb0ec1b61f349e5cc36b2028e9e7ca765be05e49641c97241274753067b4
Expand All @@ -596,10 +599,14 @@ sphinxcontrib-jsmath==1.0.1 \
--hash=sha256:2ec2eaebfb78f3f2078e73666b1415417a116cc848b72e5172e596c871103178 \
--hash=sha256:a9925e4a4587247ed2191a22df5f6970656cb8ca2bd6284309578f2153e0c4b8
# via sphinx
sphinxcontrib-mermaid==1.0.0 \
--hash=sha256:2e8ab67d3e1e2816663f9347d026a8dee4a858acdd4ad32dd1c808893db88146 \
--hash=sha256:60b72710ea02087f212028feb09711225fbc2e343a10d34822fe787510e1caa3
# via -r doc/requirements.in
sphinxcontrib-openapi==0.8.4 \
--hash=sha256:50911c18d452d9390ee3a384ef8dc8bde6135f542ba55691f81e1fbc0b71014e \
--hash=sha256:df883808a5b5e4b4113ad697185c43a3f42df3dce70453af78ba7076907e9a20
# via -r requirements.in
# via -r doc/requirements.in
sphinxcontrib-qthelp==1.0.7 \
--hash=sha256:053dedc38823a80a7209a80860b16b722e9e0209e32fea98c90e4e6624588ed6 \
--hash=sha256:e2ae3b5c492d58fcbd73281fbd27e34b8393ec34a073c792642cd8e529288182
Expand Down
1 change: 1 addition & 0 deletions router/BUILD.bazel
Original file line number Diff line number Diff line change
Expand Up @@ -5,6 +5,7 @@ go_library(
srcs = [
"connector.go",
"dataplane.go",
"doc.go",
"fnv1aCheap.go",
"metrics.go",
"serialize_proxy.go",
Expand Down
1 change: 1 addition & 0 deletions router/cmd/router/main.go
Original file line number Diff line number Diff line change
Expand Up @@ -12,6 +12,7 @@
// See the License for the specific language governing permissions and
// limitations under the License.

// Router is a SCION border router implementation as a system process.
package main

import (
Expand Down
2 changes: 1 addition & 1 deletion router/connector.go
Original file line number Diff line number Diff line change
Expand Up @@ -27,7 +27,7 @@ import (
"github.com/scionproto/scion/router/control"
)

// Connector implements the Dataplane API of the router control process. It sets
// Connector implements the Dataplane interface used by the router control API. It sets
// up connections for the DataPlane.
type Connector struct {
DataPlane DataPlane
Expand Down
13 changes: 8 additions & 5 deletions router/control/conf.go
Original file line number Diff line number Diff line change
Expand Up @@ -12,6 +12,8 @@
// See the License for the specific language governing permissions and
// limitations under the License.

// Package control is the configuration API of the router and specifies the management interface
// expected of the router.
package control

import (
Expand All @@ -27,8 +29,8 @@ import (
"github.com/scionproto/scion/private/topology"
)

// Dataplane is the interface that a dataplane has to support to be controlled
// by this controller.
// Dataplane is the interface that this controller or the http status handler expect from the
// Dataplane.
type Dataplane interface {
CreateIACtx(ia addr.IA) error
AddInternalInterface(ia addr.IA, local netip.AddrPort) error
Expand Down Expand Up @@ -66,13 +68,13 @@ type ObservableDataplane interface {
ListSiblingInterfaces() ([]SiblingInterface, error)
}

// InternalInterface represents the internal interface of a router.
// InternalInterface represents the internal underlay interface of a router.
type InternalInterface struct {
IA addr.IA
Addr netip.AddrPort
}

// ExternalInterface represents an external interface of a router.
// ExternalInterface represents an external underlay interface of a router.
type ExternalInterface struct {
// InterfaceID is the identifier of the external interface.
IfID uint16
Expand All @@ -82,7 +84,8 @@ type ExternalInterface struct {
State InterfaceState
}

// SiblingInterface represents a sibling interface of a router.
// SiblingInterface represents a sibling underlay interface of a router. A sibling interface
// is an external interface owned by another router in the same AS.
type SiblingInterface struct {
// InterfaceID is the identifier of the external interface.
IfID uint16
Expand Down
25 changes: 25 additions & 0 deletions router/doc.go
Original file line number Diff line number Diff line change
@@ -0,0 +1,25 @@
// Copyright 2024 SCION Association
//
// Licensed under the Apache License, Version 2.0 (the "License");
// you may not use this file except in compliance with the License.
// You may obtain a copy of the License at
//
// http://www.apache.org/licenses/LICENSE-2.0
//
// Unless required by applicable law or agreed to in writing, software
// distributed under the License is distributed on an "AS IS" BASIS,
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
// See the License for the specific language governing permissions and
// limitations under the License.

// Package router implements the SCION border router (BR) component as a self-contained process.
//
// The code in this package is organized as follows:
// - connector.go: implementation of the management API.
// - dataplane.go: forwards packets between underlay connections.
// - fnv1aCheap.go: a domain-specific implementation of the fnv1a hash function.
// - metrics.go: manages the monitoring sensors.
// - serialize_proxy.go: a domain-specific implementation of gopacket.SerializeBuffer.
// - svc.go: maps a service address to a set of possible destinations.
// - subpackages and tests.
package router
3 changes: 2 additions & 1 deletion router/mgmtapi/api.go
Original file line number Diff line number Diff line change
Expand Up @@ -12,6 +12,7 @@
// See the License for the specific language governing permissions and
// limitations under the License.

// Package mgmtapi implements the http status API of the router.
package mgmtapi

import (
Expand All @@ -23,7 +24,7 @@ import (
"github.com/scionproto/scion/router/control"
)

// Server implements the Control Service API.
// Server implements the http status API of the router.
type Server struct {
Config http.HandlerFunc
Info http.HandlerFunc
Expand Down
Loading