Skip to content

Commit

Permalink
Update README.md
Browse files Browse the repository at this point in the history
  • Loading branch information
@balotofi
balotofi authored Oct 26, 2024
1 parent 9bf596c commit 38289c9
Showing 1 changed file with 37 additions and 134 deletions.
171 changes: 37 additions & 134 deletions README.md
View file
Original file line number Diff line number Diff line change
@@ -1,165 +1,68 @@
# Build-A-Satellite-Docs
# BIRDS Build-A-Satellite Documentation Site

This is a *bare-minimum* template to create a [Jekyll] site that:
Welcome to the BIRDS Build-A-Satellite Documentation Site! This platform provides a comprehensive guide for designing, building, testing, and launching a small satellite. Whether you’re a beginner or an experienced developer, our documentation is structured to assist you at every stage of the satellite development process.

- uses the [Just the Docs] theme;
- can be built and published on [GitHub Pages];
- can be built and previewed locally, and published on other platforms.
## About the Project

More specifically, the created site:
BIRDS-OSP is dedicated to empowering individuals, research groups, and educational institutions with limited resources to embark on satellite missions. This documentation is designed for those aiming to understand and develop a satellite from the ground up, focusing on open-source tools and affordable methods for accessible satellite technology.

- uses a gem-based approach, i.e. uses a `Gemfile` and loads the `just-the-docs` gem;
- uses the [GitHub Pages / Actions workflow] to build and publish the site on GitHub Pages.
### Key Features

To get started with creating a site, simply:
- **Step-by-Step Guides**: Detailed instructions covering each phase, from concept design to in-orbit operation.
- **Hardware and Software Specifications**: Comprehensive information on components, materials, software, and libraries.
- **Code Repositories**: Links to essential open-source codebases and development tools.
- **Troubleshooting and FAQ**: Solutions to common issues and tips for overcoming challenges.
- **Community Support**: Join our community to get advice, share experiences, and collaborate with other developers.

1. click "[use this template]" to create a GitHub repository
2. go to Settings > Pages > Build and deployment > Source, and select GitHub Actions
## Getting Started

If you want to maintain your docs in the `docs` directory of an existing project repo, see [Hosting your docs from an existing project repo](#hosting-your-docs-from-an-existing-project-repo).
### Prerequisites

After completing the creation of your new site on GitHub, update it as needed:
Before diving in, make sure you have the following:

## Replace the content of the template pages
- Basic knowledge of electronics and programming.
- Access to [List of Required Tools and Software, e.g., CAD software, programming languages].
- Familiarity with Git and GitHub for accessing project repositories.

Update the following files to your own content:
### Setting Up

- `index.md` (your new home page)
- `README.md` (information for those who access your site repo on GitHub)
1. **Clone the Repository**: Download the documentation repository to get started.
```bash
git clone https://github.com/your-repo/satellite-docs.git
```
2. **Navigate the Site**: Explore our structured guides:
- [Design & Planning](#)
- [Component Selection](#)
- [Assembly & Testing](#)
- [Launch Preparations](#)

## Changing the version of the theme and/or Jekyll
3. **Join the Community**: Connect with other developers and contributors in our [Forum/Discord/Slack Channel].

Simply edit the relevant line(s) in the `Gemfile`.
## Contributing

## Adding a plugin
We welcome contributions! Here’s how you can help:

The Just the Docs theme automatically includes the [`jekyll-seo-tag`] plugin.
1. **Improve Documentation**: Submit updates to enhance clarity, correct errors, or add new sections.
2. **Suggest Features**: Share your ideas to improve the documentation or add resources.
3. **Report Issues**: Encountered a problem? Submit an issue on our GitHub page.

To add an extra plugin, you need to add it in the `Gemfile` *and* in `_config.yml`. For example, to add [`jekyll-default-layout`]:
### Contribution Guidelines

- Add the following to your site's `Gemfile`:
Please refer to our [Contribution Guide](#) for more details on coding standards, branch naming conventions, and testing requirements.

```ruby
gem "jekyll-default-layout"
```
## Contact

- And add the following to your site's `_config.yml`:
For questions, suggestions, or support, reach out to our team at [contact@projectemail.com](mailto:contact@projectemail.com) or join the [Community Forum](#).

```yaml
plugins:
- jekyll-default-layout
```
Note: If you are using a Jekyll version less than 3.5.0, use the `gems` key instead of `plugins`.

## Publishing your site on GitHub Pages

1. If your created site is `YOUR-USERNAME/YOUR-SITE-NAME`, update `_config.yml` to:

```yaml
title: YOUR TITLE
description: YOUR DESCRIPTION
theme: just-the-docs
url: https://YOUR-USERNAME.github.io/YOUR-SITE-NAME
aux_links: # remove if you don't want this link to appear on your pages
Template Repository: https://github.com/YOUR-USERNAME/YOUR-SITE-NAME
```

2. Push your updated `_config.yml` to your site on GitHub.

3. In your newly created repo on GitHub:
- go to the `Settings` tab -> `Pages` -> `Build and deployment`, then select `Source`: `GitHub Actions`.
- if there were any failed Actions, go to the `Actions` tab and click on `Re-run jobs`.

## Building and previewing your site locally

Assuming [Jekyll] and [Bundler] are installed on your computer:

1. Change your working directory to the root directory of your site.

2. Run `bundle install`.

3. Run `bundle exec jekyll serve` to build your site and preview it at `localhost:4000`.

The built site is stored in the directory `_site`.

## Publishing your built site on a different platform

Just upload all the files in the directory `_site`.

## Customization

You're free to customize sites that you create with this template, however you like!

[Browse our documentation][Just the Docs] to learn more about how to use this theme.

## Hosting your docs from an existing project repo

You might want to maintain your docs in an existing project repo. Instead of creating a new repo using the [just-the-docs template](https://github.com/just-the-docs/just-the-docs-template), you can copy the template files into your existing repo and configure the template's Github Actions workflow to build from a `docs` directory. You can clone the template to your local machine or download the `.zip` file to access the files.

### Copy the template files

1. Create a `.github/workflows` directory at your project root if your repo doesn't already have one. Copy the `pages.yml` file into this directory. GitHub Actions searches this directory for workflow files.

2. Create a `docs` directory at your project root and copy all remaining template files into this directory.

### Modify the GitHub Actions workflow

The GitHub Actions workflow that builds and deploys your site to Github Pages is defined by the `pages.yml` file. You'll need to edit this file to that so that your build and deploy steps look to your `docs` directory, rather than the project root.

1. Set the default `working-directory` param for the build job.

```yaml
build:
runs-on: ubuntu-latest
defaults:
run:
working-directory: docs
```

2. Set the `working-directory` param for the Setup Ruby step.

```yaml
- name: Setup Ruby
uses: ruby/setup-ruby@v1
with:
ruby-version: '3.1'
bundler-cache: true
cache-version: 0
working-directory: '${{ github.workspace }}/docs'
```

3. Set the path param for the Upload artifact step:

```yaml
- name: Upload artifact
uses: actions/upload-pages-artifact@v1
with:
path: "docs/_site/"
```

4. Modify the trigger so that only changes within the `docs` directory start the workflow. Otherwise, every change to your project (even those that don't affect the docs) would trigger a new site build and deploy.

```yaml
on:
push:
branches:
- "main"
paths:
- "docs/**"
```

## Licensing and Attribution

This repository is licensed under the [MIT License]. You are generally free to reuse or extend upon this code as you see fit; just include the original copy of the license (which is preserved when you "make a template"). While it's not necessary, we'd love to hear from you if you do use this template, and how we can improve it for future use!

The deployment GitHub Actions workflow is heavily based on GitHub's mixed-party [starter workflows]. A copy of their MIT License is available in [actions/starter-workflows].

----

[^1]: [It can take up to 10 minutes for changes to your site to publish after you push the changes to GitHub](https://docs.github.com/en/pages/setting-up-a-github-pages-site-with-jekyll/creating-a-github-pages-site-with-jekyll#creating-your-site).
----

[Jekyll]: https://jekyllrb.com
[Just the Docs]: https://just-the-docs.github.io/just-the-docs/
Expand Down

0 comments on commit 38289c9

Please sign in to comment.