From 1f68e7b16e623d5a440f2b3dc7852ba9fd60bced Mon Sep 17 00:00:00 2001 From: Sijie Yang Date: Mon, 30 Oct 2023 16:16:02 +0800 Subject: [PATCH] Update website (#13) - Add access statistics - Add algolia search - Fix typos in docs --- website/docs/further_readings/benchmark.md | 2 +- website/docs/further_readings/conformance.md | 8 +- .../docs/how_to_contribute/contribute_docs.md | 4 +- .../how_to_contribute/development_guides.md | 2 +- website/docs/intro.md | 12 +-- website/docs/tutorial/core_concepts.md | 2 +- website/docusaurus.config.js | 95 +++++-------------- .../how_to_contribute/contribute_docs.md | 4 +- .../how_to_contribute/development_guides.md | 2 +- 9 files changed, 44 insertions(+), 87 deletions(-) diff --git a/website/docs/further_readings/benchmark.md b/website/docs/further_readings/benchmark.md index 210abda71..b893a5a4c 100644 --- a/website/docs/further_readings/benchmark.md +++ b/website/docs/further_readings/benchmark.md @@ -42,7 +42,7 @@ Each server program is compiled in release mode and configured to run in single- The application layer protocol used for testing was HTTP/3, while various typical scenarios were tested, including web browsing, image loading, and video playback. We conducted tests in both long connection and short connection scenarios. -- **Long connection scenario**: The purpose of the scenario is to test the protocol stack's capacity for handling requests by constantly sending multiple requests per connection. The selected sizes of page, image, video files were 5KB, 15KB, and 2MB respectively according to the median statistics from the [HTTP Archive](https://httparchive.org/reports/page-weight#bytesHtml). +- **Long connection scenario**: The purpose of the scenario is to test the protocol stack's capacity for handling requests by constantly sending multiple requests per connection. The selected sizes of page, image, and video files were 5KB, 15KB, and 2MB respectively according to the median statistics from the [HTTP Archive](https://httparchive.org/reports/page-weight#bytesHtml). - **Short connection scenario**: The purpose of the scenario is to test the protocol stack's capacity for handshake by sending only one request per connection. Additionally, we intentionally selected a relatively small response size of 1KB. diff --git a/website/docs/further_readings/conformance.md b/website/docs/further_readings/conformance.md index dcac16b0d..7d600a324 100644 --- a/website/docs/further_readings/conformance.md +++ b/website/docs/further_readings/conformance.md @@ -5,7 +5,7 @@ sidebar_position: 3 # Protocol conformance test -We perform protocol conformance tests based on the methodology introduced in a paper titled ["Formal specification and testing of QUIC"](https://dl.acm.org/doi/10.1145/3341302.3342087) published at SIGCOMM 2019. We have upgraded the initial formal specification to incorporate support for QUIC v1 and resolved some issues in the ivy tool chain. +We perform protocol conformance tests based on the methodology introduced in a paper titled ["Formal specification and testing of QUIC"](https://dl.acm.org/doi/10.1145/3341302.3342087) published at SIGCOMM 2019. We have upgraded the initial formal specification to incorporate support for QUIC v1 and resolved some issues in the ivy toolchain. ## Formal specification of QUIC @@ -24,11 +24,11 @@ That is, from the specification we can produce an automated tester that takes on ## Advantages -This approach has certain advantages when compared to interoperablilty testing. +This approach has certain advantages when compared to interoperability testing. -* The specification-based tester can generate stimulus that can't be produced by any current implementation and perhaps would only be produced by attackers. Because it is randomized, it tends to generate the unusual cases that specifiers may not have considered. +* The specification-based tester can generate stimulus that can't be produced by any current implementation and perhaps would only be produced by attackers. Because it is randomized, it tends to generate unusual cases that specifiers may not have considered. -* It checks for actual specification compliance and not just for correct interopation. The compliance to the specification is important for future protocol developers who need to ensure compatibility with legacy implementations. +* It checks for actual specification compliance and not just for correct interopation. Compliance with the specification is important for future protocol developers who need to ensure compatibility with legacy implementations. * The formal specification can be seen as documentation, since it gives an unambiguous interpretation of statements made in natural language in the IETF specification documents. diff --git a/website/docs/how_to_contribute/contribute_docs.md b/website/docs/how_to_contribute/contribute_docs.md index 0b77c73a6..6674da98c 100644 --- a/website/docs/how_to_contribute/contribute_docs.md +++ b/website/docs/how_to_contribute/contribute_docs.md @@ -31,8 +31,8 @@ $ sudo apt-get update && apt-get install -y npm First download the full repository: ```bash -$ git clone https://github.com/tencent/tquic-website -$ cd tquic-website +$ git clone https://github.com/tencent/tquic +$ cd tquic/website $ npm install ``` diff --git a/website/docs/how_to_contribute/development_guides.md b/website/docs/how_to_contribute/development_guides.md index 4f8d7c025..aa8fb43db 100644 --- a/website/docs/how_to_contribute/development_guides.md +++ b/website/docs/how_to_contribute/development_guides.md @@ -18,7 +18,7 @@ The top directories are as followings: | fuzz/ | Fuzzing tests | | interop/ | Interoperability testing | | include/ | Generated header files for C/C++ | -| docs/ | Documents | +| website/ | TQUIC website for documents | :::tip The header file `include/tquic.h` should be updated if any changes are made to the `src/ffi.rs`. diff --git a/website/docs/intro.md b/website/docs/intro.md index b38f04be0..f62b257fc 100644 --- a/website/docs/intro.md +++ b/website/docs/intro.md @@ -9,7 +9,7 @@ sidebar_position: 1 When [TCP](https://en.wikipedia.org/wiki/Transmission_Control_Protocol#Historical_origin) was first developed in the 1970s, it's unlikely anyone could have predicted that we would still be relying on it 50 years later. While TCP has undergone numerous changes over the years, many experts believe that it might be nearing the end of the road. As society becomes increasingly dependent on the internet, [TCP is unfortunately not keeping up with the ever-increasing demands](https://dl.acm.org/doi/10.1145/3098822.3098842). -[QUIC](https://datatracker.ietf.org/doc/html/rfc9000) is a new general-purpose, secured, multiplexed transport-layer protocol. It offers several enhancements, aiming to eventually replacing TCP, which could enable Internet transport to continue evolving and solve many of the problems plaguing the Internet. With QUIC being chosen as the foundation for [HTTP/3](https://datatracker.ietf.org/doc/html/rfc9114), it is reasonable to expect that the protocol will carry a significantly larger share of Internet traffic. +[QUIC](https://datatracker.ietf.org/doc/html/rfc9000) is a new general-purpose, secured, multiplexed transport-layer protocol. It offers several enhancements, aiming to eventually replace TCP, which could enable Internet transport to continue evolving and solve many of the problems plaguing the Internet. With QUIC being chosen as the foundation for [HTTP/3](https://datatracker.ietf.org/doc/html/rfc9114), it is reasonable to expect that the protocol will carry a significantly larger share of Internet traffic. The following are some of the key features of QUIC: - Zero RTT Connection establishment @@ -24,10 +24,10 @@ The following are some of the key features of QUIC: ## What is TQUIC? -TQUIC is an implementation of the IETF QUIC protocol. It is a high performance, lightweight and cross-platform QUIC library. +TQUIC is an implementation of the IETF QUIC protocol. It is a high-performance, lightweight, and cross-platform QUIC library. -## Features and Advantanges +## Features and Advantages * **Rich features**: TQUIC supports all big features conforming with [QUIC, HTTP/3 RFCs](https://quicwg.org/). @@ -36,13 +36,13 @@ TQUIC supports all big features conforming with [QUIC, HTTP/3 RFCs](https://quic TQUIC is designed for high performance and low latency. Relevant details can be found in the [benchmark result](further_readings/benchmark). * **Pluggable congestion control**: -TQUIC supports various congtestion control algorithm, including [CUBIC](https://datatracker.ietf.org/doc/html/rfc8312), [BBR](https://dl.acm.org/doi/pdf/10.1145/3009824), [BBRv3](https://datatracker.ietf.org/meeting/117/materials/slides-117-ccwg-bbrv3-algorithm-bug-fixes-and-public-internet-deployment-00), [COPA](https://www.usenix.org/conference/nsdi18/presentation/arun). +TQUIC supports various congestion control algorithms, including [CUBIC](https://datatracker.ietf.org/doc/html/rfc8312), [BBR](https://dl.acm.org/doi/pdf/10.1145/3009824), [BBRv3](https://datatracker.ietf.org/meeting/117/materials/slides-117-ccwg-bbrv3-algorithm-bug-fixes-and-public-internet-deployment-00), and [COPA](https://www.usenix.org/conference/nsdi18/presentation/arun). * **Multipath QUIC**: TQUIC supports [Multipath](https://datatracker.ietf.org/doc/html/draft-ietf-quic-multipath) to enable the simultaneous usage of multiple paths for a single connection. * **Easy to Use** -TQUIC is easy to use. It supports flexible setting and detailed observability. +TQUIC is easy to use. It supports flexible settings and detailed observability. * **Cross platform**: TQUIC runs on almost anything to which Rust compiles. It provides [APIs for Rust/C/C++](category/api-reference). @@ -51,7 +51,7 @@ TQUIC runs on almost anything to which Rust compiles. It provides [APIs for Rust TQUIC is written in a memory safety language and immune to Buffer Overflow vulnerability and other memory-related bugs. * **High quality**: -Extensive automated testing, including unit testing, fuzz testing, integration testing, performance benchmarking, interoperability testing and more. +Extensive automated testing, including unit testing, fuzz testing, integration testing, performance benchmarking, interoperability testing, and more. * **Protocol Compliance**: TQUIC has been [verified by formal specification using the Ivy tool](further_readings/conformance). It has also passed [IETF interoperability tests](https://github.com/marten-seemann/quic-interop-runner). diff --git a/website/docs/tutorial/core_concepts.md b/website/docs/tutorial/core_concepts.md index eea4f219f..4c47f52af 100644 --- a/website/docs/tutorial/core_concepts.md +++ b/website/docs/tutorial/core_concepts.md @@ -23,7 +23,7 @@ The QUIC connection is not strictly bound to a single network path. It uses conn ## Stream -The **Stream** provide a lightweight, ordered byte-stream abstraction to an application. +The **Stream** provides a lightweight, ordered byte-stream abstraction to an application. Streams can be unidirectional or bidirectional: **unidirectional** streams carry data from the initiator to its peer; **bidirectional** streams allow for data to be sent in both directions. diff --git a/website/docusaurus.config.js b/website/docusaurus.config.js index 75908b4e3..b03e326a8 100644 --- a/website/docusaurus.config.js +++ b/website/docusaurus.config.js @@ -60,6 +60,14 @@ const config = { ], ], + scripts: [ + // Access Statistics + { + src: 'https://hm.baidu.com/hm.js?fd65f9f2d0d936713c5ec3e52dc1b497', + async: true, + }, + ], + themeConfig: /** @type {import('@docusaurus/preset-classic').ThemeConfig} */ ({ @@ -83,10 +91,6 @@ const config = { type: 'localeDropdown', position: 'right', }, - { - type: 'search', - position: 'right', - }, { href: 'https://github.com/tencent/tquic', position: 'right', @@ -173,73 +177,26 @@ const config = { theme: lightCodeTheme, darkTheme: darkCodeTheme, }, - }), - plugins: [ - [ - require.resolve("@cmfcmf/docusaurus-search-local"), - { - // whether to index docs pages - indexDocs: true, - - // Whether to also index the titles of the parent categories in the sidebar of a doc page. - // 0 disables this feature. - // 1 indexes the direct parent category in the sidebar of a doc page - // 2 indexes up to two nested parent categories of a doc page - indexDocSidebarParentCategories: 0, - - // whether to index blog pages - indexBlog: true, - - // whether to index static pages. /404.html is never indexed - indexPages: false, - - // language of your documentation, see next section - language: ["en"], - - // setting this to "none" will prevent the default CSS to be included. The default CSS - // comes from autocomplete-theme-classic, which you can read more about here: - // https://www.algolia.com/doc/ui-libraries/autocomplete/api-reference/autocomplete-theme-classic/ - // When you want to overwrite CSS variables defined by the default theme, make sure to suffix your - // overwrites with `!important`, because they might otherwise not be applied as expected. See the - // following comment for more information: https://github.com/cmfcmf/docusaurus-search-local/issues/107#issuecomment-1119831938. - style: undefined, - - // The maximum number of search results shown to the user. This does _not_ affect performance of - // searches, but simply does not display additional search results that have been found. - maxSearchResults: 8, - - // lunr.js-specific settings - lunr: { - // When indexing your documents, their content is split into "tokens". - // Text entered into the search box is also tokenized. - // This setting configures the separator used to determine where to split the text into tokens. - // By default, it splits the text at whitespace and dashes. - // Note: Does not work for "ja" and "th" languages, since these use a different tokenizer. - tokenizerSeparator: /[\s\-]+/, - // https://lunrjs.com/guides/customising.html#similarity-tuning - // This parameter controls the importance given to the length of a document and its fields. This - // value must be between 0 and 1, and by default it has a value of 0.75. Reducing this value - // reduces the effect of different length documents on a term’s importance to that document. - b: 0.75, - // This controls how quickly the boost given by a common word reaches saturation. Increasing it - // will slow down the rate of saturation and lower values result in quicker saturation. The - // default value is 1.2. If the collection of documents being indexed have high occurrences - // of words that are not covered by a stop word filter, these words can quickly dominate any - // similarity calculation. In these cases, this value can be reduced to get more balanced results. - k1: 1.2, - // By default, we rank pages where the search term appears in the title higher than pages where - // the search term appears in just the text. This is done by "boosting" title matches with a - // higher value than content matches. The concrete boosting behavior can be controlled by changing - // the following settings. - titleBoost: 5, - contentBoost: 1, - tagsBoost: 3, - parentCategoriesBoost: 2, // Only used when indexDocSidebarParentCategories > 0 - } + algolia: { + // The application ID provided by Algolia + appId: '61LALVEO97', + + // Public API key: it is safe to commit it + apiKey: 'dd58ffb613c5141209183b8c3707d42f', + + indexName: 'TQUIC_INDEX', + + // Optional: see doc section below + contextualSearch: true, + + // Optional: Algolia search parameters + searchParameters: {}, + + // Optional: path for search page that enabled by default (`false` to disable it) + searchPagePath: 'search', }, - ], - ], + }), }; module.exports = config; diff --git a/website/i18n/zh/docusaurus-plugin-content-docs/current/how_to_contribute/contribute_docs.md b/website/i18n/zh/docusaurus-plugin-content-docs/current/how_to_contribute/contribute_docs.md index 35a92fc0b..f9c6338b8 100644 --- a/website/i18n/zh/docusaurus-plugin-content-docs/current/how_to_contribute/contribute_docs.md +++ b/website/i18n/zh/docusaurus-plugin-content-docs/current/how_to_contribute/contribute_docs.md @@ -31,8 +31,8 @@ $ sudo apt-get update && apt-get install -y npm 首先下载完整的代码库： ```bash -$ git clone https://github.com/tencent/tquic-website -$ cd tquic-website +$ git clone https://github.com/tencent/tquic +$ cd tquic/website $ npm install ``` diff --git a/website/i18n/zh/docusaurus-plugin-content-docs/current/how_to_contribute/development_guides.md b/website/i18n/zh/docusaurus-plugin-content-docs/current/how_to_contribute/development_guides.md index dfaa5dba9..e4b7d8538 100644 --- a/website/i18n/zh/docusaurus-plugin-content-docs/current/how_to_contribute/development_guides.md +++ b/website/i18n/zh/docusaurus-plugin-content-docs/current/how_to_contribute/development_guides.md @@ -18,7 +18,7 @@ TQUIC项目的顶级目录如下: | fuzz/ | 模糊测试 | | interop/ | 互操作性测试 | | include/ | 自动生成的C/C++头文件 | -| docs/ | 文档 | +| website/ | TQUIC文档网站 | :::tip 如果对`src/ffi.rs`进行了修改，应该更新头文件 `include/tquic.h`。