nuttx/Documentation/_templates/layout.html

54 lines
2.3 KiB
HTML
Raw Normal View History

<!--
Documentation/_templates/layout.html
Licensed to the Apache Software Foundation (ASF) under one or more
contributor license agreements. See the NOTICE file distributed with
this work for additional information regarding copyright ownership. The
ASF licenses this file to you 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.
-->
{% extends "!layout.html" %}
{% block sidebartitle %}
Documentation: brand new layout for NuttX documentation. The documentation grew one page at a time, so the tree follows the history of who wrote what and not the shape of NuttX. Scheduling is spread over three places, a driver page can sit above the subsystem that owns it, and the front page lists everything at the same level. That is a lot to face when all you want to know is where the scheduler lives. This change files every page under the code it describes. It is a move, not a rewrite: outside the ten pages named below, every page keeps the text that is already in master, and no page's text is deleted. What it does: * Groups the table of contents into nine chapters. * Moves the OS subsystems under os/: scheduling, memory, drivers, filesystem, networking, IPC, interrupts, libs, time. * Renames the platform pages to the names the source tree uses, and derives their tags from the tree instead of by hand. * Splits guides/ by subject. * Adds Documentation/redirects.py, with a rule for every page that left its old path, so old URLs keep working. The redirect page also carries a link's #anchor across to the new page. Ten pages have text that is new or rewritten. Nine of them are the landing page of a chapter, which has to exist for the new structure: index the front page os/index OS Design os/scheduling/index Scheduling os/interrupts/index Interrupts os/ipc/index IPC os/time/index Time and timers about/index About developing/index Developing NuttX ReleaseNotes/index Release notes The tenth is os/libs/libbuiltin, the only page here with technical content: libs/libbuiltin/ had no page at all. Five SVG diagrams come with these pages, hand-written XML with no editor metadata. Nothing outside Documentation/ is touched. How it was checked: * Sphinx builds with -W: no warnings, and no document left outside a toctree. * A script, offered in the PR, proves the narrow claim this rests on. For every page outside the ten named above it erases what a move touches -- link target, path, tag line, toctree block, table border -- from the whole old text and the whole new text, and requires the two to be byte for byte identical. It also requires every sentence of a deleted page to turn up somewhere, and every page that left its old path to have a redirect, from a URL that existed, to where its content went. It exits non-zero and names the page if any of that is not true, and it tests added pages too, so forgetting to declare one cannot make it pass. * An independent audit checked 133 factual claims on these ten pages against the tree, one shell command per claim: 130 confirmed, 1 refuted and fixed here, 2 not checkable. * tools/checkpatch.sh is clean over the range. The diff is large because moving a page changes every link that points to it. Most of it is pure renames, and board pages that gained one tag line. Assisted-by: Claude:claude-opus-5
2026-09-30 17:55:03 +02:00
{#- Sphinx passes the logo as `logo_url`; it used to be `logo`, and when
that changed this template quietly stopped rendering the mark at all,
leaving only the theme's house icon. Accept both so the logo shows on
either. -#}
{%- set nuttx_logo = logo_url if logo_url else (pathto('_static/' + logo, 1) if logo else none) %}
<a href="{{ pathto(master_doc) }}" class="nuttx-brand">
{% if nuttx_logo %}
<img src="{{ nuttx_logo }}" class="logo" alt="{{ _('NuttX logo') }}"/>
{% endif %}
{% if not theme_logo_only %}
<span class="nuttx-brand-name">{{ project }}</span>
{% endif %}
</a>
<div class="version-selector">
Documentation: brand new layout for NuttX documentation. The documentation grew one page at a time, so the tree follows the history of who wrote what and not the shape of NuttX. Scheduling is spread over three places, a driver page can sit above the subsystem that owns it, and the front page lists everything at the same level. That is a lot to face when all you want to know is where the scheduler lives. This change files every page under the code it describes. It is a move, not a rewrite: outside the ten pages named below, every page keeps the text that is already in master, and no page's text is deleted. What it does: * Groups the table of contents into nine chapters. * Moves the OS subsystems under os/: scheduling, memory, drivers, filesystem, networking, IPC, interrupts, libs, time. * Renames the platform pages to the names the source tree uses, and derives their tags from the tree instead of by hand. * Splits guides/ by subject. * Adds Documentation/redirects.py, with a rule for every page that left its old path, so old URLs keep working. The redirect page also carries a link's #anchor across to the new page. Ten pages have text that is new or rewritten. Nine of them are the landing page of a chapter, which has to exist for the new structure: index the front page os/index OS Design os/scheduling/index Scheduling os/interrupts/index Interrupts os/ipc/index IPC os/time/index Time and timers about/index About developing/index Developing NuttX ReleaseNotes/index Release notes The tenth is os/libs/libbuiltin, the only page here with technical content: libs/libbuiltin/ had no page at all. Five SVG diagrams come with these pages, hand-written XML with no editor metadata. Nothing outside Documentation/ is touched. How it was checked: * Sphinx builds with -W: no warnings, and no document left outside a toctree. * A script, offered in the PR, proves the narrow claim this rests on. For every page outside the ten named above it erases what a move touches -- link target, path, tag line, toctree block, table border -- from the whole old text and the whole new text, and requires the two to be byte for byte identical. It also requires every sentence of a deleted page to turn up somewhere, and every page that left its old path to have a redirect, from a URL that existed, to where its content went. It exits non-zero and names the page if any of that is not true, and it tests added pages too, so forgetting to declare one cannot make it pass. * An independent audit checked 133 factual claims on these ten pages against the tree, one shell command per claim: 130 confirmed, 1 refuted and fixed here, 2 not checkable. * tools/checkpatch.sh is clean over the range. The diff is large because moving a page changes every link that points to it. Most of it is pure renames, and board pages that gained one tag line. Assisted-by: Claude:claude-opus-5
2026-09-30 17:55:03 +02:00
<label class="nuttx-version-label" for="nuttx-version">{{ _('Version') }}</label>
<select id="nuttx-version"
onchange="javascript:location.href = this.value;">
{#- The Makefile builds this list as "latest,$(NUTTX_VERSIONS)", so an
unset NUTTX_VERSIONS leaves a trailing comma and an empty entry.
Dropping the blanks here keeps a nameless option pointing at ./../
out of the menu. -#}
{% for nuttx_version in nuttx_versions.split(',') if nuttx_version.strip() %}
{%- set nuttx_version = nuttx_version.strip() %}
2020-11-26 15:15:49 -03:00
<option value="{{ url_root }}../{{ nuttx_version }}" {% if nuttx_version == version %}selected="selected"{% endif %}>{{ nuttx_version }}</option>
{% endfor %}
</select>
</div>
{% include "searchbox.html" %}
{% endblock %}