Update build dependencies, improve README
Change-Id: I9b0b7b0cc6f5991075ce144564ce567916b6fe6f
diff --git a/README.md b/README.md
index 3118681..3aab7da 100644
--- a/README.md
+++ b/README.md
@@ -1,18 +1,45 @@
+<div align="center">
+
+[<img alt height="65" src="_static/ndn-logo.svg"/>](https://named-data.net/)
+
# NDN Packet Format Specification
-## Prerequisites
+</div>
-To "compile" the specification in HTML format, you must first install the Sphinx documentation generator.
+This repository contains the base packet format specification of the Named Data
+Networking (NDN) protocol.
-If you're running Ubuntu Linux:
+An HTML version of the specification can be viewed online at
+<https://docs.named-data.net/NDN-packet-spec/>.
+
+## Compiling from source
+
+### Prerequisites
+
+To "compile" the specification in HTML format, you must first install the
+[Sphinx](https://www.sphinx-doc.org/en/master/) documentation generator and a
+few other dependencies. To do so, first make sure that the following packages
+are installed and up to date:
+
+* make
+* python 3.8 or later
+* pip
+
+For instance, on Ubuntu Linux you can use the following commands:
sudo apt install make python3-pip
- pip3 install -U pip
- pip3 install -r requirements.txt
+ python3 -m pip install -U pip
-If you're running macOS or another operating system, see the instructions at https://www.sphinx-doc.org/en/master/usage/installation.html
+On other operating systems, you can either use your preferred package manager or
+follow [pip's installation instructions](https://pip.pypa.io/en/stable/installation/).
-## Compilation
+Finally, run:
+
+ python3 -m pip install -r requirements.txt
+
+to install the recommended version of Sphinx and its dependencies.
+
+### Compilation
Just type:
@@ -24,6 +51,8 @@
make latexpdf
-Sphinx will generate a `.tex` file and will try to create a `.pdf` document from it using `pdflatex` (which must be installed).
+Sphinx will generate a `.tex` file and will try to compile it into a PDF document
+using `latexmk` and `pdflatex` (which must be installed). If successful, the final
+`.pdf` file can be found in `_build/latex`.
For further options, type `make help`.
diff --git a/conf.py b/conf.py
index 25e80e5..e1e0dcc 100644
--- a/conf.py
+++ b/conf.py
@@ -7,13 +7,13 @@
# https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information
project = 'NDN Packet Format Specification'
-copyright = '2013-2022, Named Data Networking Project'
+copyright = '2013-2023, Named Data Networking Project'
+author = 'Named Data Networking Project'
# The short X.Y version.
version = '0.3'
-
# The full version, including alpha/beta/rc tags.
-release = '0.3'
+release = version
# -- General configuration ---------------------------------------------------
@@ -25,6 +25,9 @@
templates_path = ['_templates']
exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store']
+# Use ABNF syntax highlighting by default for code blocks.
+highlight_language = 'abnf'
+
# -- Options for HTML output -------------------------------------------------
# https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output
@@ -36,8 +39,9 @@
# so a file named "default.css" will overwrite the builtin "default.css".
html_static_path = ['_static']
-html_title = '{} {}'.format(project, version)
+html_title = f'{project} v{version}'
html_logo = '_static/ndn-logo.svg'
+html_last_updated_fmt = ''
html_copy_source = False
html_show_sourcelink = False
@@ -50,9 +54,9 @@
'color-brand-primary': '#fd7800',
'color-brand-content': '#fd7800',
},
+ 'source_repository': 'https://github.com/named-data/NDN-packet-spec',
+ 'source_branch': 'master',
}
-# Use ABNF syntax highlighting by default for code blocks.
-highlight_language = 'abnf'
-
+pygments_style = 'tango'
pygments_dark_style = 'material'
diff --git a/requirements.txt b/requirements.txt
index 7639064..1952c37 100644
--- a/requirements.txt
+++ b/requirements.txt
@@ -1,2 +1,2 @@
-furo == 2022.9.29
-sphinx ~= 5.0
+furo == 2022.12.7
+sphinx ~= 6.0