How to Contribute or Add a New Page to BeWhere Documentation

Welcome to the BeWhere Documentation project! If you'd like to contribute or add a new page to the documentation, follow these steps to get started.

Prerequisites

Before contributing, ensure you have the following tools installed:

Git
Python 3.x
MkDocs (for local testing)

Steps for Contributing or Adding a New Page

1. Fork the Repository

Navigate to the bewhere-docs Repository.
Click the Fork button to create your own copy of the repository.

2. Clone Your Fork Locally

Clone your forked repository to your local machine using the following command:

git clone https://bitbucket.org/your-username/bewhere-docs.git

Navigate to the cloned directory:

cd bewhere-docs

3. Checkout a New Branch

For all contributions, create a new branch from develop to keep the changes organized and prevent any issues with the main codebase. To create and switch to a new branch:

git checkout develop
git pull origin develop
git checkout -b add-new-page

Replace add-new-page with a meaningful branch name describing your changes.

4. Add Your New Page

Create a New Markdown File

In the docs/ directory, create a new .md file for your page (e.g., new-feature.md).

Write Content

Use Markdown syntax to structure your content properly. Example:

# Introduction
This is the new page content.

## Feature 1
- Description of feature 1

Update the mkdocs.yml file to include your new page in the navigation. Open the mkdocs.yml file and add your page under the appropriate section:

nav:
  - Home: index.md
  - Platform:
      - User Guide: platform.md
      - New Feature: new-feature.md  # Add your new page here

Note: Ensure that the indentation in mkdocs.yml is correct, as YAML is indentation-sensitive.

5. Commit Your Changes

Once you've added your new page and updated the navigation, commit your changes:

git add .
git commit -m "Added new page: new-feature"

6. Push Changes to Your Fork

Push your changes to your forked repository:

git push origin add-new-page

7. Create a Pull Request

Go to your forked repository on Bitbucket.
Click the Compare & pull request button.
Ensure the base branch is develop and your branch is selected as the compare branch.
Add a description of your changes and submit the pull request.

8. Review and Merge

Once your pull request is submitted, it will be reviewed by the repository maintainers. After the review process, your changes will be merged into the develop branch.

Deployment

Once your changes are merged into develop, follow these steps to deploy the documentation.

1. Build the Documentation

Run the following command to generate the static site files:

mkdocs build

This will generate a site/ directory containing all the necessary files for deployment.

2. Deploy the Documentation

To deploy the documentation, copy the contents of the site/ directory to the designated web server or hosting service. You can use various methods such as:

Secure Copy (SCP):

scp -r site/* user@server:/path/to/documentation

rsync (for efficient updates):

rsync -avz site/ user@server:/path/to/documentation

FTP/SFTP Clients (such as Cyberduck or WinSCP, if required by the hosting service).

3. Verify Deployment

Once the upload is complete, visit the website URL to verify that your changes are live.

Additional Notes

Folder Structure: Ensure that new pages are placed under the appropriate section of the docs/ folder.
Linking to Other Pages: Use relative links to reference other pages within the documentation. Example:
```
[See the User Guide](platform.md)
```

Thank you for contributing to BeWhere Documentation! We appreciate your help in improving the documentation for everyone.