ReadtheDocs Overview

This repo contains material, code, and resources for Zcash ReadtheDocs environment. It is intended as a staging area for existing documentation to be updated during the ReadtheDocs migration. Additionally, it provides a local and non-local development environment using Sphinx, ReadtheDocs, and Python3+

Installation

Below you will find setup instructions for a few common platforms. Please follow the procedure specific to your respective platform.

Linux

Install PIP:

sudo apt-get install python3-pip

Get required packages for ReadtheDocs build:

pip3 install sphinx_rtd_theme sphinx sphinx-autobuild sphinx_fontawesome recommonmark sphinx-sitemap sphinx-copybutton

macOS

If you are using brew, please issue the following:

brew install python3
pip3 install sphinx_rtd_theme sphinx sphinx-autobuild sphinx_fontawesome recommonmark sphinx-sitemap sphinx-copybutton

If you are not using brew, please verify version of OS:

sw_vers -productVersion

Using the version output from sw_vers -productVersion, download the according package or follow the install from source instructions here:

https://www.macports.org/install.php

Once you have successfully installed macports, configure sphinx using the below commands:

sudo port install py36-sphinx
sudo port select --set python python36
sudo port select --set sphinx py36-sphinx

Windows

Install PIP:

easy_install pip3

Get required packages for ReadtheDocs build:

pip3 install sphinx_rtd_theme sphinx sphinx-autobuild sphinx_fontawesome recommonmark sphinx-sitemap sphinx-copybutton

If you are unable to build the above packages, please compile them from source:

[sphinx_rtd_theme] (https://github.com/rtfd/sphinx_rtd_theme)

[sphinx_fontawesome] (https://github.com/fraoustin/sphinx_fontawesome)

Setup

To use the Zcash ReadtheDocs development environment, please issue the following command:

git clone https://gitlab.com/zcash-docs/zcash-docs.git
cd zcash-docs

Here you will notice some important directories and files:

📄 make.bat

📄 Makefile

📁 source

Local Development

There are several options to create targets from the ReadtheDocs development environment. The core functionality is maintained in the below files, located in ./source/ :

📄 conf.py (configuration file used to support local/non-local environment)

📄 index.rst (root page for ReadtheDocs to generate sibling documents)

Build

If you are current in the project root directory issue the following command to generate a local html instance of ReadtheDocs:

make html

You can find the generated root html file in ./build/html/ as index.html

Non-Local Development

This non-local implementation of Zcash ReadtheDocs found here

The dashboard corresponding to this environment is located here