Update Doc Build Process Doc

The current build process is documented but not implemented anymore. This change adds a make target that uses Docker as an isolated environment for building the doc, and updates the doc accordingly. Signed-off-by: Brett Logan <brett.t.logan@ibm.com>
hyperledger · Aug 27, 2020 · ddffd90 · ddffd90
1 parent ceb56c7
commit ddffd90
Show file tree

Hide file tree

Showing 7 changed files with 19 additions and 224 deletions.
diff --git a/Makefile b/Makefile
@@ -22,6 +22,7 @@
 #   - docker-tag-latest - re-tags the images made by 'make docker' with the :latest tag
 #   - docker-tag-stable - re-tags the images made by 'make docker' with the :stable tag
 #   - docker-thirdparty - pulls thirdparty images (kafka,zookeeper,couchdb)
+#   - docs - builds the documentation in html format
 #   - gotools - installs go tools like golint
 #   - help-docs - generate the command reference docs
 #   - idemixgen - builds a native idemixgen binary
@@ -319,3 +320,7 @@ unit-test-clean:
 .PHONY: filename-spaces
 spaces:
 	@scripts/check_file_name_spaces.sh
+
+.PHONY: docs
+docs:
+	@docker run --rm -v $$(pwd):/docs n42org/tox:3.4.0 sh -c 'cd /docs && tox -e docs'
diff --git a/docs/Pipfile b/docs/Pipfile
diff --git a/docs/Pipfile.lock b/docs/Pipfile.lock
diff --git a/docs/source/dev-setup/build.rst b/docs/source/dev-setup/build.rst
@@ -20,18 +20,15 @@ of your changes using your web browser before you open a pull request.
 You need to download the following prerequisites before you can build the
 documentation:
 
-- `Python 3.7 <https://wiki.python.org/moin/BeginnersGuide/Download>`__
-- `Pipenv <https://pipenv.readthedocs.io/en/latest/#install-pipenv-today>`__
+- `Docker <https://docs.docker.com/get-docker/>`__
 
 After you make your updates to the documentation source files, you can generate
 a build that includes your changes by running the following commands:
 
 ::
 
-    cd fabric/docs
-    pipenv install
-    pipenv shell
-    make html
+    cd fabric
+    make docs
 
 This will generate all the html files in the ``docs/build/html`` folder. You can
 open any file to start browsing the updated documentation using your browser. If you

diff --git a/docs/source/docs_guide.md b/docs/source/docs_guide.md
@@ -193,27 +193,20 @@ your GitHub account.
 2. Install the following prerequisites; you may need to adjust depending on your
    OS:
 
-   * [Python 3.7](https://wiki.python.org/moin/BeginnersGuide/Download)
-   * [Pipenv](https://docs.pipenv.org/en/latest/#install-pipenv-today)
+   * [Docker](https://docs.docker.com/get-docker/)
 
 3. For US English:
    ```bash
-   cd $HOME/git
    git clone git@github.com:hyperledger/fabric.git
-   cd fabric/docs
-   pipenv install
-   pipenv shell
-   make html
+   cd fabric
+   make docs
    ```
 
-   For Malayalam (for example):
+   For International Languages (Malayalam as an example):
    ```bash
-   cd $HOME/git
    git clone git@github.com:hyperledger/fabric-docs-i18n.git
-   cd fabric-docs-18n/docs/locale/ml_IN
-   pipenv install
-   pipenv shell
-   make -e SPHINXOPTS="-D language='ml'" html
+   cd fabric
+   make docs-lang-ml_IN
    ```
 
    The `make` command generates documentation html files in the `build/html/`
@@ -222,7 +215,7 @@ your GitHub account.
 
 4. Now make a small change to a file, and rebuild the documentation to verify
    that your change was as expected. Every time you make a change to the
-   documentation you will of course need to rerun `make html`.
+   documentation you will of course need to rerun `make docs`.
 
 5. If you'd like, you may also run a local web server with the following
    commands (or equivalent depending on your OS):

diff --git a/scripts/functions.sh b/scripts/functions.sh
@@ -34,6 +34,7 @@ function filterExcludedAndGeneratedFiles {
         '(^|/)vendor\/'
         '(^|/)Pipfile$'
         '(^|/)Pipfile\.lock$'
+        '(^|/)tox\.ini$'
     )
 
     local filter

diff --git a/tox.ini b/tox.ini
@@ -8,11 +8,11 @@ skipsdist=true
 [testenv:docs]
 deps = -rdocs/requirements.txt
 commands =
-    sphinx-build -b html -n -d {envtmpdir}/doctrees ./docs/source {toxinidir}/docs/_build/html
-    echo "Generated docs available in {toxinidir}/docs/_build/html"
+    sphinx-build -b html -n -d {envtmpdir}/doctrees ./docs/source {toxinidir}/docs/build/html
+    echo "Generated docs available in {toxinidir}/docs/build/html"
 whitelist_externals = echo
 
 [testenv:docs-linkcheck]
 deps = -rdocs/requirements.txt
 commands =
-    sphinx-build -b linkcheck -d {envtmpdir}/doctrees ./docs/source {toxinidir}/docs/_build/linkcheck
+    sphinx-build -b linkcheck -d {envtmpdir}/doctrees ./docs/source {toxinidir}/docs/build/linkcheck