Skip to content

Commit

Permalink
doc: mild doc improvements (#4676)
Browse files Browse the repository at this point in the history
Update the TC members list. Add a link to the online godoc in the
Contribute section. Try and improve package descriptions (in the router
only for now) to make the code easier to navigate with godoc.
  • Loading branch information
jiceatscion authored Jan 13, 2025
1 parent f49d3cd commit b01e71d
Show file tree
Hide file tree
Showing 10 changed files with 70 additions and 20 deletions.
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

0 comments on commit b01e71d

Please sign in to comment.