This is an automated email from the ASF dual-hosted git repository.
raiden00 pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/nuttx-website.git
The following commit(s) were added to refs/heads/master by this push:
new aeefa4fd5 README update.
aeefa4fd5 is described below
commit aeefa4fd5150ae35470fcf67d6a0d010e2349b74
Author: Tomasz 'CeDeROM' CEDRO <[email protected]>
AuthorDate: Fri Sep 20 03:05:53 2024 +0200
README update.
Explain website organization, sources organization, local build process.
Signed-off-by: Tomasz 'CeDeROM' CEDRO <[email protected]>
---
README.md | 126 +++++++++++++++++++++++++++++++++++++++++++++++++-------------
1 file changed, 100 insertions(+), 26 deletions(-)
diff --git a/README.md b/README.md
index 2d4a6e1e5..c95d78ba6 100644
--- a/README.md
+++ b/README.md
@@ -17,44 +17,118 @@ limitations under the License.
{% endcomment %}
-->
-# How to update the project's web site
+# Apache NuttX RTOS Website
-## Running locally
+Source code (written in [RubyGems](https://rubygems.org/))
+for [our offical project's website](https://nuttx.apache.org)
+is stored here along with the build-and-publish automation scripts
+(using GitHub CI).
-Before opening a pull request, you can preview your contributions by
-running from within the directory:
+[NuttX Technical Documentation](https://nuttx.apache.org/docs/latest/)
+is a sublocation of the project website, therefore is built and bundled here,
+but documentation sources are part of the
+[NuttX source code
repository](https://github.com/apache/nuttx/tree/master/Documentation)
+in order to stay in sync with the upstream code.
+Documentation uses [Sphinx](https://www.sphinx-doc.org/) generator tools
+to produce HTML output.
+
+Please keep in mind that Website (this repository) and Documentation (NuttX
+repository) have different source origins and common resulting location.
+
+
+## Providing the Updates
+
+Fork the repository, clone it to a local machine, make changes,
+commit changes onto a dedicated branch, push the branch onto your
+fork repository, GitHub will help you create a Pull Request.
+
+Remember to use signed commits and report single problem per PR.
+
+Make sure to preview local changes before submitting a Pull Request.
+
+If you already submitted a Pull Request, but some changes needs to be made,
+add modified files with `git add <your_file>`, then `git commit --amend`
+to update existing commit, then `git push -f <your_fork> <your_branch>`
+in order to update code under existing Pull Request.
+
+
+## Updating the Website
+
+Website source code resides at top location of this repository.
+
+Before opening a Pull Request, you should preview your contributions.
+
+You first need to install Ruby Gems on a local machine:
+
+```
+sudo apt install git ruby ruby-dev bundler
+```
+
+Then you can build and preview the results with:
```
-export GEM_HOME=$HOME/.gem # Adjust this path as you want
-export PATH=$PATH:$GEM_HOME/bin
-bundle exec jekyll serve
-Open [http://localhost:4000](http://localhost:4000)
+git clone https://github.com/apache/nuttx-website
+cd nuttx-website/
+export GEM_HOME=$HOME/.gem # Adjust this path as you want.
+export PATH=$PATH:$GEM_HOME/bin # Add Gem binaries to the path.
+bundle install # Install required packages.
+bundle exec jekyll serve # Build and start local web server.
```
-Note: The Gemfile.lock may contain some platform specific pins
-you may want to regenerate this by deleting `Gemfile.lock`
-and running `bundle update`. This is currently locked
-for x86_64-linux, darwin, and freebsd by using the
-`bundle lock --add-platform foo` command.
+Preview should be visible at [http://localhost:4000](http://localhost:4000).
+
+**Note:** The `Gemfile.lock` may contain some platform specific pins.
+You may want to regenerate it by deleting `Gemfile.lock`
+and running `bundle update`. Pins can be locked
+for `x86_64-linux`, `Darwin`, `FreeBSD`, and other build hosts with
+`bundle lock --add-platform <your_platform>` command.
+
+
+## Updating the Documentaion
+NuttX Technical Documentation is part of the
+[NuttX source code
repository](https://github.com/apache/nuttx/tree/master/Documentation).
-## Pushing to site
+Before opening a Pull Request, you should preview your contributions.
-Site is updated by a CI job that runs the `publish.sh` script. Once this
-runs it the results will be visible [here](https://nuttx.apache.org).
+You first need to install Python3 and PipEnv.
-### Force Deployment
+```
+sudo apt install git python3 pipenv
+```
-If a dependency has changed such as the external documentation you may
-need to force the deployment CI to run. This can be done from the [CI
-Actions](https://github.com/apache/nuttx-website/actions?query=workflow%3ACI)
-tab and selecting **Run workflow** -> **Branch: master** --> **Run workflow**
+You can setup build tools and create preview with:
+
+```
+git clone https://github.com/apache/nuttx
+cd nuttx/Documentation
+pipenv install
+pipenv run make html
+```
+
+Preview files should be visible at `_build/html/` directory.
+
+
+## Website Publishing
+
+Website is updated by the GitHub CI Action script that builds the RubyGem
+and Shinx part from sources, bundles them together, and then runs the
+`publish.sh` script to update the web hosting at
+[https://nuttx.apache.org](https://nuttx.apache.org).
+
+Website build-and-publish Action can be started by hand with:
+1.
[Actions](https://github.com/apache/nuttx-website/actions/workflows/main.yml).
+2. Run workflow.
+3. Branch: master.
+4. Run workflow.
-## Adding contributors
-To add a contributor to the project, or to modify existing contributors,
-edit `site/_data/contributors.yml`.
-The [project members](http://localhost:4000/community.html#project-members)
-list will re-generate.
+## Important Locations
+
+* Apache NuttX RTOS Project Members, Mentors, PMC/IPMC members, and Committers
+are listed at
+[https://nuttx.apache.org/community-members/](https://nuttx.apache.org/community-members/).
+ Source file for this site is located at
[_data/contributors.yml](_data/contributors.yml).
+* Project details and link references are at
[_data/project.yml](_data/project.yml).
