The documentation website requires Python with PIP and Nginx to be installed and configured on your machine. Modern versions of both should work.
If using MacOS all can be installed with Homebrew
pip install Sphinx
pip install recommonmark
See more detail http://www.sphinx-doc.org/en/stable/markdown.html
pip install sphinx_rtd_theme
See more detail https://github.com/rtfd/sphinx_rtd_theme
pip install sphinxcontrib-newsfeed
pip install sphinxcontrib-spelling
Install nginx and config like below. Set document root accordingly.
# nginx conf
server {
listen 80;
server_name docs.bvbrc.local;
root /BV-BRC-Docs/docroot/_build/html;
# to avoid Cross-Origin Request Blocked error
location / {
if ($request_method = 'OPTIONS') {
add_header 'Access-Control-Allow-Origin' '*';
add_header 'Access-Control-Allow-Methods' 'GET, OPTIONS';
add_header 'Access-Control-Allow-Headers' 'Keep-Alive,User-Agent,X-Requested-With,If-Modified-Since,Cache-Control,Content-Type,Content-Range,Range';
return 204;
}
if ($request_method = 'GET') {
add_header 'Access-Control-Allow-Origin' '*';
add_header 'Access-Control-Allow-Methods' 'GET, OPTIONS';
}
}
}
Add record for docs.bvbrc.local in /etc/hosts with sudo
127.0.0.1 localhost
127.0.0.1 docs.bvbrc.local
Following the structure already laid out in the repository you should be able to create a .md or .rst file corresponding to what you're looking to do. In order for it to show up in the Table of Contents or landing pages make sure to link your new page to the respective index.rst located at it's corresponding spot in the heirarchy.
From within the BV-BRC-Docs/docroot directory you can run this command to rebuild the doc site.
make html
On occastion, especially with heavy TOC changes and/or static files added you make need to do a complete rebuild.
rm -rf _build && make html
We write our documentation pages in both Markdown (.md) and reStructuredText (.rst). Sphinx uses the CommonMark version of Markdown when it builds the documentation site. It is slightly different than the GitHub Flavored MarkDown used by GitHub so make sure to take note of any subtle differences. Use these resources to write and develop documentation for BV-BRC without causing warnings or failures. There is only one flavor of reStructuredText.