Blaauw Observatory Knowledgebase

This is the Github repository for information regarding the Blaauw Observatory. The documentation is hosted at readthedocs.

Here are some useful links if you want to know more about how the project is set up:

• reStructuredText (RST) Primer
• Sphinx + RST + Readthedocs Tutorial
• Readthedocs Tutorial

Making changes

You can make changes by editing files in Github directly, but then you will only be able to see and test your changes after Readthedocs compiles them. So this mostly works for small changes.

A better alternative is to set up the project locally (assuming you have a Linux system and git installed) and generate the documentation yourself:

1. Start wil cloning the repository

   git clone https://github.com/PracticalAstronomyCrew/knowledgebase.git
   # or with SSH set up (better!)
   git clone [email protected]:PracticalAstronomyCrew/knowledgebase.git
   
   # Then move into the cloned repository
   cd knowledgebase

2. Create a virtual environment, activate it and install the Sphinx dependencies

   # Creates a subdirectory .venv, change the name if you want
   python3 -m venv .venv
   
   source .venv/bin/activate   # Activates the virtual environment
   
   # Installs the dependencies for compiling the documentation
   pip install -r ./docs/requirements.txt

3. Build the html pages of the local documentation:

   # Run 'make html' in the ./docs subdirectory
   make html -C docs

4. If this was successful the HTML pages can now be found in the directory: docs/build/html. Open them (for instance with firefox) like this:

   firefox ./docs/build/html/index.html

Now you should be ready to make changes to the knowledgebase. If you are ready to see your changes locally, you can rebuild (step 3.) and reopen the pages (step 4.).

Finally, if you are completely done and satisfied with your changes (make sure it builds successfully!) you can add, commit and push your changes.