From 5c8dac0008092a39cdc337fbf85d121282c16231 Mon Sep 17 00:00:00 2001 From: Richard Date: Fri, 7 Aug 2026 23:09:12 -0700 Subject: [PATCH 1/4] docs: convert the software page to the house style Full simplified technical English pass over docs/source/software.rst, applying the seven rules and the approved-term table from the docs skill. PASS docs/source/software.rst em-dash 0->0 | semicolon 1->0 | banned 6->1 | words 936->914 (-2%) terms: choose 5->1, the unit 1->0 OVERALL: PASS Style only. No facts, numbers, procedures or step order were changed. Headings, cross-references, image paths and substitutions are unchanged, verified mechanically against origin/main. Sphinx builds clean under -n. Co-Authored-By: Claude Opus 5 (1M context) Claude-Session: https://claude.ai/code/session_01HqTCarGCgTRWBQ1ysG8XFD --- docs/source/software.rst | 63 ++++++++++++++++++++-------------------- 1 file changed, 31 insertions(+), 32 deletions(-) diff --git a/docs/source/software.rst b/docs/source/software.rst index 0408a5aef..b82c016e3 100644 --- a/docs/source/software.rst +++ b/docs/source/software.rst @@ -2,19 +2,19 @@ Software Setup ============== -Once you've built or otherwise obtained a PiFinder, here's how to set up a fresh SD card to run it. The recommended way is to download the current prebuilt release image and use the Raspberry Pi imager to burn it and configure your wifi. If you prefer, you can build an image from scratch following the instructions below. +Once you've built or otherwise obtained a PiFinder, set up a fresh SD card to run it. The recommended way is to download the current prebuilt release image, then use the Raspberry Pi imager to write it to the card and set up your WiFi. If you prefer, build an image from scratch by following the instructions below. Prebuilt Release Image ---------------------- -The image files on our release pages bundle the correct Raspberry Pi OS version, the installed and configured PiFinder software, and all the deep sky catalog images. This is the recommended way to get PiFinder onto an SD card, however you built or purchased the unit. +The image files on our release pages bundle the correct Raspberry Pi OS version, the installed and configured PiFinder software, and all the deep-sky catalog images. This is the recommended way to put the PiFinder software on an SD card, whether you built or bought your PiFinder. * Download the latest release image from our `releases page `_ * Install the Raspberry Pi imager: https://www.raspberrypi.com/software/ -* Run the imager, click 'Choose OS', select 'Use Custom', then choose the image you downloaded +* Run the imager, click 'Choose OS', select 'Use Custom', then select the image you downloaded .. image:: images/software/rpi_imager_001.png :width: 47% @@ -25,11 +25,11 @@ The image files on our release pages bundle the correct Raspberry Pi OS version, * To let the PiFinder connect to your network, click the gear icon at the lower left and fill in: - * SSID: The name of your wifi network - * Password: The password for your wifi network - * Wireless LAN Country: Where you live, so wifi follows local regulations + * SSID: The name of your WiFi network + * Password: The password for your WiFi network + * Wireless LAN Country: Where you live, so WiFi follows local regulations -* You can also set your locale and keyboard, but the PiFinder software ignores these; they only affect the underlying operating system. +* You can also set your locale and keyboard. These affect only the underlying operating system, and the PiFinder software ignores them. .. image:: images/software/rpi_imager_003.png :width: 47% @@ -38,9 +38,9 @@ The image files on our release pages bundle the correct Raspberry Pi OS version, :width: 47% .. important:: - Do not set the hostname or username/password. SSH is enabled on this image by default. + Do not set the hostname or username/password. This image enables SSH by default. -* Click 'Select Storage' and choose the SD card on your computer +* Click 'Select Storage' and select the SD card on your computer * Click 'Write' to start .. note:: @@ -48,38 +48,37 @@ The image files on our release pages bundle the correct Raspberry Pi OS version, refuses to write it), the download was incomplete or corrupted. Download the release image again and retry. -Once writing is complete, insert the SD card into your PiFinder and power it up. The first boot takes a bit longer as it expands the filesystem to fill the card, so be patient. +Once the imager finishes writing, insert the SD card into your PiFinder and turn it on. The first start takes longer than usual, because the PiFinder expands the filesystem to fill the card. Be patient. -With the software installed, you're ready for the :doc:`Quick Start Guide` and a night of observing. +The software is now installed. Continue to the :doc:`Quick Start Guide` for a night of observing. Build From Scratch ------------------ .. warning:: - You probably do not want to do this. These instructions are primarily for developers - who are making a new image file from scratch. To just use your PiFinder you will - want to use the instructions above to download and use a pre-built image for your - sd card. + You probably do not want to do this. These instructions are for developers who build + a new image file from scratch. To just use your PiFinder, follow the instructions + above to download a prebuilt image and write it to your SD card. -You can do this completely headless (no monitor or keyboard) if you like. +You can do all of this headless (no monitor or keyboard). General Pi Setup ^^^^^^^^^^^^^^^^^^^^^^^^ .. important:: - You must use the specific Raspberry Pi OS version listed here or the PiFinder software will not work. The software is designed and tested for a specific version with each release. + You must use the specific Raspberry Pi OS version listed here, or the PiFinder software will not work. We design and test the software for one specific version with each release. -* Create the image using the Raspberry Pi imager. It's available for most platforms and makes it easy to set up wifi and SSH. +* Create the image with the Raspberry Pi imager. It's available for most platforms and makes it easy to set up WiFi and SSH. * Select the 64-Bit version of Pi OS (**Legacy**) Lite (No Desktop Environment) - * **Make sure you select the Legacy Bullseye option here** + * **Select the Legacy Bullseye option here** - * Set up SSH / Wifi / User and Host name using the gear icon. Below is a screengrab showing the suggested settings. + * Set up SSH, WiFi, and the user and host name with the gear icon. The screenshot below shows the suggested settings. * **The username must be** ``pifinder`` * Customize the host name, password, network settings, and locale for your needs. @@ -90,7 +89,7 @@ General Pi Setup -* Once the image is burned to an SD card, insert it into the PiFinder and power it up. The first boot will probably take a few minutes. +* Once you've written the image to an SD card, insert it into the PiFinder and turn it on. The first start takes a few minutes. * SSH into the PiFinder using ``pifinder@pifinder.local`` and the password you set up. * Update all packages. This isn't strictly required, but it's good practice. @@ -98,15 +97,15 @@ General Pi Setup * ``sudo apt upgrade`` * Enable SPI / I2C, which the screen and IMU use to communicate. - * run ``sudo raspi-config`` + * Run ``sudo raspi-config`` * Select 3 - Interface Options - * Then I4 - SPI and choose Enable - * Then I5 - I2C and choose Enable + * Select I4 - SPI, then select Enable + * Select I5 - I2C, then select Enable PiFinder Software Install ^^^^^^^^^^^^^^^^^^^^^^^^^^ -You now have a fresh install of Raspberry Pi OS. The rest of the setup is handled by the ``pifinder_setup.sh`` script in this repo. Download and run it in one step: +You now have a fresh install of Raspberry Pi OS. The ``pifinder_setup.sh`` script in this repo handles the rest of the setup. Download and run it in one step: ``wget -O - https://raw.githubusercontent.com/brickbots/PiFinder/release/pifinder_setup.sh | bash`` @@ -116,14 +115,14 @@ The script will: * Clone this repo * Install the needed packages/dependencies * Download some required astronomy data files -* Set up Wifi access point capabilities +* Set up WiFi access point capabilities * Create a samba share for pulling images and observation logs and adding observing lists * Set up the PiFinder service to start on reboot -Once the script finishes, reboot the PiFinder: +Once the script finishes, restart the PiFinder: ``sudo shutdown -r now`` -Booting takes up to two minutes, but you should see the startup screen before long: +Startup takes up to two minutes, but the startup screen appears before long: .. image:: ../../images/screenshots/WELCOME_001_docs.png :alt: Startup log @@ -132,11 +131,11 @@ Booting takes up to two minutes, but you should see the startup screen before lo Catalog Image Download ^^^^^^^^^^^^^^^^^^^^^^ -The PiFinder can display catalog object images when they're present on your SD card. These images take about 5gb of space and can take several hours or more to download, but you can cancel and resume at any time. +The PiFinder can display catalog object images when they're on your SD card. These images use about 5gb of space and can take several hours or more to download. You can cancel and resume at any time. -The :ref:`software:prebuilt release image` already includes these images and is much quicker to download as a single file from your main computer. +The :ref:`software:prebuilt release image` already includes these images. It's much quicker to download as a single file from your main computer. -To download the catalog images, put your PiFinder in WIFI client mode so it can reach the internet, then SSH into it using the password you set up initially. +To download the catalog images, put your PiFinder in WiFi client mode so it can reach the internet, then SSH into it using the password you set up initially. Once connected, type: @@ -152,4 +151,4 @@ The PiFinder checks which images are missing and starts downloading. You can mo :alt: Image Download -There are 13,000+ images, so it takes a while, but you can do it across multiple sessions. The PiFinder uses whichever images you have on hand each time you observe. +There are 13,000+ images, so the download takes a while. You can do it across multiple sessions. The PiFinder uses whichever images you have each time you observe. From 0a6fd39fd3f1dd08978efe5c06634ec46d77035e Mon Sep 17 00:00:00 2001 From: Richard Date: Fri, 7 Aug 2026 23:35:26 -0700 Subject: [PATCH 2/4] docs: keep "boot" for the machine's own startup sequence The style pass converted boot -> start here, but sd_card and troubleshooting deliberately kept "boot", and cross-page review found they are right. Two frozen headings contain the word - sd_card's "First boot" and troubleshooting's "The screen is blank, or it won't finish booting" - so it cannot leave the manual. This page had ended up contradicting a page it links to with near-identical sentences: sd_card says "The first boot from a freshly imaged card takes longer than usual", while this said "The first start...". The approved term "turn on" still covers the user action. "boot" covers only the machine's own startup sequence. The two are different concepts, and the term table needs a row saying so - noted for a skill follow-up. Co-Authored-By: Claude Opus 5 (1M context) Claude-Session: https://claude.ai/code/session_01HqTCarGCgTRWBQ1ysG8XFD --- docs/source/software.rst | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/source/software.rst b/docs/source/software.rst index b82c016e3..8511d89f2 100644 --- a/docs/source/software.rst +++ b/docs/source/software.rst @@ -48,7 +48,7 @@ The image files on our release pages bundle the correct Raspberry Pi OS version, refuses to write it), the download was incomplete or corrupted. Download the release image again and retry. -Once the imager finishes writing, insert the SD card into your PiFinder and turn it on. The first start takes longer than usual, because the PiFinder expands the filesystem to fill the card. Be patient. +Once the imager finishes writing, insert the SD card into your PiFinder and turn it on. The first boot takes longer than usual, because the PiFinder expands the filesystem to fill the card. Be patient. The software is now installed. Continue to the :doc:`Quick Start Guide` for a night of observing. @@ -89,7 +89,7 @@ General Pi Setup -* Once you've written the image to an SD card, insert it into the PiFinder and turn it on. The first start takes a few minutes. +* Once you've written the image to an SD card, insert it into the PiFinder and turn it on. The first boot takes a few minutes. * SSH into the PiFinder using ``pifinder@pifinder.local`` and the password you set up. * Update all packages. This isn't strictly required, but it's good practice. @@ -122,7 +122,7 @@ The script will: Once the script finishes, restart the PiFinder: ``sudo shutdown -r now`` -Startup takes up to two minutes, but the startup screen appears before long: +Booting takes up to two minutes, but the startup screen appears before long: .. image:: ../../images/screenshots/WELCOME_001_docs.png :alt: Startup log From 9e90b928c846155ac1cee2dd84965092f56f18bf Mon Sep 17 00:00:00 2001 From: Richard Date: Sat, 8 Aug 2026 17:55:46 -0700 Subject: [PATCH 3/4] docs(software): un-nest the SPI/I2C setup steps "Enable SPI / I2C" and its four raspi-config steps rendered as sub-items of "sudo apt upgrade", two levels below where they belong, which made enabling the buses look like part of updating packages. Promote it to a sibling of "Update all packages" and nest the raspi-config steps under it. Verified in the built HTML: the item now sits at the same list depth as "SSH into the PiFinder". Wording unchanged. Co-Authored-By: Claude Opus 5 (1M context) Claude-Session: https://claude.ai/code/session_01HqTCarGCgTRWBQ1ysG8XFD --- docs/source/software.rst | 11 ++++++----- 1 file changed, 6 insertions(+), 5 deletions(-) diff --git a/docs/source/software.rst b/docs/source/software.rst index 8511d89f2..ab354cb9f 100644 --- a/docs/source/software.rst +++ b/docs/source/software.rst @@ -96,11 +96,12 @@ General Pi Setup * ``sudo apt update`` * ``sudo apt upgrade`` - * Enable SPI / I2C, which the screen and IMU use to communicate. - * Run ``sudo raspi-config`` - * Select 3 - Interface Options - * Select I4 - SPI, then select Enable - * Select I5 - I2C, then select Enable +* Enable SPI / I2C, which the screen and IMU use to communicate. + + * Run ``sudo raspi-config`` + * Select 3 - Interface Options + * Select I4 - SPI, then select Enable + * Select I5 - I2C, then select Enable PiFinder Software Install ^^^^^^^^^^^^^^^^^^^^^^^^^^ From 40f3ee3f2db23811896e3fbb3a57461c33b412b4 Mon Sep 17 00:00:00 2001 From: Richard Date: Sat, 8 Aug 2026 17:56:21 -0700 Subject: [PATCH 4/4] docs(software): the last stray "reboot" -> "boot" The page normalised reboot -> restart everywhere else, leaving one "start on reboot". "restart" is the wrong replacement here: the service starts on every boot, not only after a restart. Under the settled turn on vs boot rule, "boot" is the approved word for the machine's own startup sequence, so "start on boot" is both accurate and in style. Co-Authored-By: Claude Opus 5 (1M context) Claude-Session: https://claude.ai/code/session_01HqTCarGCgTRWBQ1ysG8XFD --- docs/source/software.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/source/software.rst b/docs/source/software.rst index ab354cb9f..7bf0d9867 100644 --- a/docs/source/software.rst +++ b/docs/source/software.rst @@ -118,7 +118,7 @@ The script will: * Download some required astronomy data files * Set up WiFi access point capabilities * Create a samba share for pulling images and observation logs and adding observing lists -* Set up the PiFinder service to start on reboot +* Set up the PiFinder service to start on boot Once the script finishes, restart the PiFinder: ``sudo shutdown -r now``