From ac0eaff94117757046867bc92797d6c2dae78cd4 Mon Sep 17 00:00:00 2001 From: Chris Johns Date: Mon, 13 Nov 2017 11:51:23 +1100 Subject: Use '.. toctree::' and not '.. include::' in the User Manual. - Change all suitable '.. include::' to TOC tree. - Remove unused and not needed sections. - Fix the conf.py to not exclude some files. Close #3232. --- user/conf.py | 31 -------------- user/config/build.rst | 7 ---- user/config/index.rst | 10 ----- user/config/runtime.rst | 7 ---- user/hardware/index.rst | 10 +++-- user/hosts/index.rst | 10 +++-- user/index.rst | 2 +- user/installation/index.rst | 14 ++++--- user/installation/prefixes-sandboxing.rst | 3 +- user/start/installation.rst | 27 ------------ user/start/quick.rst | 68 ------------------------------- user/start/transition.rst | 7 ---- user/tools/index.rst | 14 ++++--- user/waf/build.rst | 11 ----- user/waf/config.rst | 11 ----- user/waf/index.rst | 15 ------- user/waf/install.rst | 11 ----- 17 files changed, 30 insertions(+), 228 deletions(-) delete mode 100644 user/config/build.rst delete mode 100644 user/config/index.rst delete mode 100644 user/config/runtime.rst delete mode 100644 user/start/installation.rst delete mode 100644 user/start/quick.rst delete mode 100644 user/start/transition.rst delete mode 100644 user/waf/build.rst delete mode 100644 user/waf/config.rst delete mode 100644 user/waf/index.rst delete mode 100644 user/waf/install.rst (limited to 'user') diff --git a/user/conf.py b/user/conf.py index a97b81a..b644cee 100644 --- a/user/conf.py +++ b/user/conf.py @@ -5,37 +5,6 @@ from conf import * project = "RTEMS User Manual" -exclude_patterns = ['config/build.rst', - 'config/runtime.rst', - - 'start/quick.rst', - - 'hosts/os.rst', - 'hosts/prefixes.rst', - 'hosts/macos.rst', - 'hosts/posix.rst', - 'hosts/windows.rst', - - 'installation/prefixes-sandboxing.rst', - 'installation/releases.rst', - 'installation/developer.rst', - 'installation/kernel.rst', - - 'hardware/targets.rst', - 'hardware/architectures.rst', - 'hardware/bsps.rst', - 'hardware/tiers.rst', - - 'tools/build.rst', - 'tools/simulation.rst', - - 'test/create.rst', - 'test/running.rst', - 'start/installation.rst', - 'start/transition.rst', - - 'waf/index.rst'] - latex_documents = [ ('index', 'user.tex', diff --git a/user/config/build.rst b/user/config/build.rst deleted file mode 100644 index 7478cc6..0000000 --- a/user/config/build.rst +++ /dev/null @@ -1,7 +0,0 @@ -.. comment SPDX-License-Identifier: CC-BY-SA-4.0 - -Build Configuration -=================== -.. index:: Build Configuration - -XXX: build configuration diff --git a/user/config/index.rst b/user/config/index.rst deleted file mode 100644 index ef19702..0000000 --- a/user/config/index.rst +++ /dev/null @@ -1,10 +0,0 @@ -.. comment SPDX-License-Identifier: CC-BY-SA-4.0 - - -Config -****** - -XXX: All about rtems config - -.. include:: build.rst -.. include:: runtime.rst diff --git a/user/config/runtime.rst b/user/config/runtime.rst deleted file mode 100644 index 6af382d..0000000 --- a/user/config/runtime.rst +++ /dev/null @@ -1,7 +0,0 @@ -.. comment SPDX-License-Identifier: CC-BY-SA-4.0 - -Runtime -======= -.. index:: Runtime Configuration - -XXX: runtime config diff --git a/user/hardware/index.rst b/user/hardware/index.rst index d27ecb8..b1f45b9 100644 --- a/user/hardware/index.rst +++ b/user/hardware/index.rst @@ -12,7 +12,9 @@ Hardware This section discusses supported Hardware, Architectures, Board Support Packages, and running RTEMS on real hardware and simulators. -.. include:: targets.rst -.. include:: architectures.rst -.. include:: bsps.rst -.. include:: tiers.rst +.. toctree:: + + targets + architectures + bsps + tiers diff --git a/user/hosts/index.rst b/user/hosts/index.rst index 71111f9..b1d1273 100644 --- a/user/hosts/index.rst +++ b/user/hosts/index.rst @@ -44,7 +44,9 @@ building tools is something you do once. Once the tools and RTEMS is built all your time can be spent writing and developing your application. Over an hour can happen and for the ARM architecture and with all BSPs it can be many hours. -.. include:: os.rst -.. include:: posix.rst -.. include:: macos.rst -.. include:: windows.rst +.. toctree:: + + os + posix + macos + windows diff --git a/user/index.rst b/user/index.rst index 3c29a64..8cbcd1b 100644 --- a/user/index.rst +++ b/user/index.rst @@ -53,7 +53,7 @@ to the Community Project hosted at http://www.rtems.org/. tools/index support/index - additional/index + glossary/index genindex diff --git a/user/installation/index.rst b/user/installation/index.rst index 6f3db6b..5a1865d 100644 --- a/user/installation/index.rst +++ b/user/installation/index.rst @@ -3,11 +3,11 @@ .. comment: Copyright (c) 2016 Chris Johns .. comment: All rights reserved. +.. index:: Installation .. _installation: Installation ************ -.. index:: Installation This section details how to set up and install the RTEMS Ecosystem. You will create a set of tools and an RTEMS kernel for your selected Board Support @@ -42,9 +42,11 @@ pass ready for you to use. The tools and kernel are stable and only bug fixes are added creating new dot point releases. The developer set up tracks the Git repositories for the tools and kernel. -.. include:: prefixes-sandboxing.rst -.. include:: releases.rst -.. include:: developer.rst -.. include:: kernel.rst - .. comment: code block warning is in kernel.rst + +.. toctree:: + + prefixes-sandboxing + releases + developer + kernel diff --git a/user/installation/prefixes-sandboxing.rst b/user/installation/prefixes-sandboxing.rst index f91def6..c7dbdca 100644 --- a/user/installation/prefixes-sandboxing.rst +++ b/user/installation/prefixes-sandboxing.rst @@ -4,12 +4,11 @@ .. comment: All rights reserved. .. _prefixes: +.. index:: Prefixes Prefixes ======== -.. index:: Prefixes - You will see the term :ref:term:`prefix` referred to thoughout this documentation and in a wide number of software packages you can download from the internet. A **prefix** is the path on your computer a software package is diff --git a/user/start/installation.rst b/user/start/installation.rst deleted file mode 100644 index 0513e4c..0000000 --- a/user/start/installation.rst +++ /dev/null @@ -1,27 +0,0 @@ -.. comment SPDX-License-Identifier: CC-BY-SA-4.0 - -.. comment: Copyright (c) 2016 Chris Johns -.. comment: All rights reserved. - -Installation -============ - -.. index:: Installation - -RTEMS is built from source on your host machine. Releases are available from -our :r:url:`ftp` and each release contains a Quick Start build guide. If you -are wanting to track changes to RTEMS as they happen or you want to make -changes to RTEMS to send back to the project on our :r:list:`devel` then you -can use the developer's version available in our :r:url:`git`. - -RTEMS supports development on a wide vararity of hosts. There is no preferred -host operating system the project requires you use. This means you are able to -decide on a host operating system that is your passion, suites your needs, or -in some cases is decided for you by your employer. Our aim is to provide a -consistent user experience and on matching hardware the experience should feel -similar. - -The RTEMS core development team uses POSIX type operating systems, that is -Unix. The :ref:`released-version` and :ref:`development-version` sections -assume Unix. Microsoft Windows is documented in a separate section -:ref:`microsoft-windows-installation`. diff --git a/user/start/quick.rst b/user/start/quick.rst deleted file mode 100644 index 199ae2c..0000000 --- a/user/start/quick.rst +++ /dev/null @@ -1,68 +0,0 @@ -.. comment SPDX-License-Identifier: CC-BY-SA-4.0 - -.. comment: Copyright (c) 2016 Chris Johns -.. comment: All rights reserved. - -Quick Start Guide -================= - -.. index:: Quick Start - -The following is a quick start guide that provides you with the basic commands -you need to build the RTEMS Tools and Kernel. - -You need to have your development host set up and ready, the -:ref:`development-host` covers what you need. - -This procedure does a development (unstable) build from Git for a POSIX -host. You can refer to the specific section that cover the specific part of the -process in detail if you have an issue. The output from the commands has been -removed and replaced with ``...``. - -Create a workspace, download the RTEMS Source Builder (RSB) and build a tool -chain (See :ref:`rtems-tools-chain`): - -.. code-block:: shell - - $ cd - $ mkdir -p development/rtems - $ cd development/rtems - $ git clone git://git.rtems.org/rtems-source-builder.git rsb - ... - $ cd rsb - $ ./source-builder/sb-check - ... - $ cd rtems - $ ../source-builder/sb-set-builder \ - --prefix=/usr/home/chris/development/rtems/5 5/rtems-sparc - ... - -Build the RTEMS Kernel (See :ref:`rtems-kernel`) by cloning the repository, -running the ``bootstrap`` procecure, building and finally installing the -kernel: - -.. code-block:: shell - - $ export PATH=$HOME/development/rtems/5/bin:$PATH - $ cd - $ cd development/rtems - $ mkdir kernel - $ cd kernel - $ git clone git://git.rtems.org/rtems.git rtems - ... - $ cd rtems - $ ./bootstrap -c && ./bootstrap -p && \ - $HOME/development/rtems/rsb/source-builder/sb-bootstrap - ... - $ cd .. - $ mkdir erc32 - $ cd erc32 - $ $HOME/development/rtems/kernel/rtems/configure --prefix=$HOME/development/rtems/5 \ - --target=sparc-rtems5 --enable-rtemsbsp=erc32 --enable-posix \ - --disable-networking - ... - $ make -j 8 - ... - $ make install - -You can now build a 3rd party library like LibBSD or an application. diff --git a/user/start/transition.rst b/user/start/transition.rst deleted file mode 100644 index ecdefe3..0000000 --- a/user/start/transition.rst +++ /dev/null @@ -1,7 +0,0 @@ -.. comment SPDX-License-Identifier: CC-BY-SA-4.0 - -Transition -=========== -.. index:: Transition, Autotools - -XXX: Transition from auto* to waf. diff --git a/user/tools/index.rst b/user/tools/index.rst index 64f4abf..6cf3509 100644 --- a/user/tools/index.rst +++ b/user/tools/index.rst @@ -14,9 +14,11 @@ of avaliable host computers users wish to develop on. This section details the tools available on the host computers to help support RTEMS users and developers. -.. include:: linker.rst -.. include:: symbols.rst -.. include:: exeinfo.rst -.. include:: trace-linker.rst -.. include:: bsp-builder.rst -.. include:: tester.rst +.. toctree:: + + linker + symbols + exeinfo + trace-linker + bsp-builder + tester diff --git a/user/waf/build.rst b/user/waf/build.rst deleted file mode 100644 index f76780c..0000000 --- a/user/waf/build.rst +++ /dev/null @@ -1,11 +0,0 @@ -.. comment SPDX-License-Identifier: CC-BY-SA-4.0 - -:orphan: - -Building -======== -.. index:: Building - -XXX: How to build. - - diff --git a/user/waf/config.rst b/user/waf/config.rst deleted file mode 100644 index dabad31..0000000 --- a/user/waf/config.rst +++ /dev/null @@ -1,11 +0,0 @@ -.. comment SPDX-License-Identifier: CC-BY-SA-4.0 - -:orphan: - -Config -======= -.. index:: Config - -XXX: waf config - - diff --git a/user/waf/index.rst b/user/waf/index.rst deleted file mode 100644 index 307e4ae..0000000 --- a/user/waf/index.rst +++ /dev/null @@ -1,15 +0,0 @@ -.. comment SPDX-License-Identifier: CC-BY-SA-4.0 - -.. _waf: - -=== -Waf -=== - -XXX: All about waf. - - -.. include:: config.rst -.. include:: build.rst -.. include:: install.rst - diff --git a/user/waf/install.rst b/user/waf/install.rst deleted file mode 100644 index 21a12ec..0000000 --- a/user/waf/install.rst +++ /dev/null @@ -1,11 +0,0 @@ -.. comment SPDX-License-Identifier: CC-BY-SA-4.0 - -:orphan: - -Installing RTEMS -================ -.. index:: Installing RTEMS - -XXX: How to install. - - -- cgit v1.2.3