From 2dfe1ce5f64a7fa792be6ba000b46ee1bacc0ffc Mon Sep 17 00:00:00 2001 From: Tom Keffer Date: Mon, 21 Aug 2023 17:17:08 -0700 Subject: [PATCH] Include an introduction in the Users Guide Link to the root index --- TODO.md | 5 +++++ docs_src/custom/introduction.md | 5 +++-- docs_src/index.md | 9 +++++---- .../{system-requirements.md => introduction.md} | 17 +++++++++++------ mkdocs.yml | 6 ++++-- 5 files changed, 28 insertions(+), 14 deletions(-) rename docs_src/usersguide/{system-requirements.md => introduction.md} (89%) diff --git a/TODO.md b/TODO.md index f79322a00..20b956794 100644 --- a/TODO.md +++ b/TODO.md @@ -2,6 +2,11 @@ Think about how `WEEWX_ROOT` is defined. +What is the subdirectory `user`? Is it station data, and therefore should be +located under `~/weewx-data`? Or, is it code, and should be installed in the +virtual environment? Same issue with a package install. + + ## Debian packaging Right now, the depository is for a "squeeze" and "buster" distribution. Do we keep adding them diff --git a/docs_src/custom/introduction.md b/docs_src/custom/introduction.md index 189510c12..e1f2b52eb 100644 --- a/docs_src/custom/introduction.md +++ b/docs_src/custom/introduction.md @@ -1,7 +1,8 @@ -# The Customization Guide +# Customization Guide This document covers the customization of WeeWX. It assumes that you have read, -and are reasonably familiar with, the *Users Guide*. +and are reasonably familiar with, the [_Users +Guide_](../../usersguide/introduction). The introduction contains an overview of the architecture. If you are only interested in customizing the generated reports you can probably skip the diff --git a/docs_src/index.md b/docs_src/index.md index e0d8a6dcf..95a632fff 100644 --- a/docs_src/index.md +++ b/docs_src/index.md @@ -6,8 +6,9 @@ stations and sensors, then generates plots, HTML pages, and monthly and yearly summary reports. It can push plots, pages, and reports to a web server, and data to many online weather services. -Initial development began in the winter of 2008-2009, with the first release -in 2009. +Initial development began in the winter of 2008-2009, with the first release in +2009. WeeWX is about 25,000 lines of code, plus another 15,000 for the hardware +drivers. The source code is hosted on [GitHub](https://github.com/weewx/weewx). Installation instructions and releases are available at @@ -65,7 +66,7 @@ you are developing a driver, skin, or other extension. source any operating system - + If you want to install WeeWX on a system with very little storage, or if you want to experiment with code that is under development, then you may want to run directly from the WeeWX sources. @@ -79,7 +80,7 @@ WeeWX includes extensive documentation, and the WeeWX developers work hard to keep it relevant and up to date. If you have questions, please consult the documentation first. -* [User's Guide](usersguide/installing) - installation, getting started, where to find things, backup/restore, troubleshooting +* [User's Guide](usersguide/introduction) - installation, getting started, where to find things, backup/restore, troubleshooting * [Customization Guide](custom/introduction) - instructions for customizing reports and plots, localization, formatting, writing extensions * [Utilities Guide](utilities/weewxd) - tools to manage stations, reports, and data * [Hardware Guide](hardware/drivers) - how to configure hardware, features of supported hardware diff --git a/docs_src/usersguide/system-requirements.md b/docs_src/usersguide/introduction.md similarity index 89% rename from docs_src/usersguide/system-requirements.md rename to docs_src/usersguide/introduction.md index 142c122f9..f5f594d3b 100644 --- a/docs_src/usersguide/system-requirements.md +++ b/docs_src/usersguide/introduction.md @@ -1,11 +1,16 @@ -# System requirements +# User's Guide -## Python +This is the complete guide to installing, configuring, and troubleshooting +WeeWX. -Python 3.7 or later is required. WeeWX V5 will not run on Python 2. +## System requirements +### Python -## Station hardware +Python 3.7 or later is required. Python 2 will not work. + + +### Station hardware WeeWX includes support for many types of weather stations. In addition to hardware support, WeeWX comes with a software simulator, useful for testing @@ -25,7 +30,7 @@ If you still cannot find your hardware, post to the [User's Group](https://groups.google.com/g/weewx-user) for help. -## Computer hardware +### Computer hardware WeeWX is written in Python, so it has the overhead associated with that language. Nevertheless, it is "fast enough" on just about any hardware. @@ -41,7 +46,7 @@ about 5.1 seconds on a RPi B+, compared to 3.0 seconds on the Fit-PC, and 0.3 seconds on a NUC with a 4th gen i5 processor. -## Time +### Time You should run some sort of time synchronization daemon to ensure that your computer has the correct time. Doing so will greatly reduce errors, especially diff --git a/mkdocs.yml b/mkdocs.yml index 2a66072f0..6b55b46dd 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -48,6 +48,8 @@ docs_dir: 'docs_src' site_dir: 'build/docs' nav: + - "Overview" : index.md + - "Quick start": - Debian: quickstarts/debian.md - RedHat: quickstarts/redhat.md @@ -56,7 +58,7 @@ nav: - git: quickstarts/git.md - "User's guide": - - "System requirements": usersguide/system-requirements.md + - "Introduction": usersguide/introduction.md - "Installing WeeWX": usersguide/installing.md - "Where to find things" : usersguide/where.md - "Running WeeWX": usersguide/running.md @@ -70,7 +72,7 @@ nav: - "Meteorological problems": usersguide/troubleshooting/meteo.md - Customization guide: - - "Introduction to customization": custom/introduction.md + - "Introduction": custom/introduction.md - "Customizing reports": custom/custom-reports.md - "Scheduling reports": custom/report-scheduling.md - "The Cheetah generator": custom/cheetah-generator.md