From 2d1a04371a8e61f9d5ba8b028f41fcbcec017b9c Mon Sep 17 00:00:00 2001 From: John DeNisco Date: Thu, 26 Jul 2018 16:21:31 -0400 Subject: [PATCH] Fix .gitignore so docs/Makefile is not ignored. Add README and Makefile. Fis gitreview. Change-Id: I3d664d9c881ce127a09b9d68c1181a7098a39074 Signed-off-by: John DeNisco --- .gitignore | 1 + docs/Makefile | 20 +++++++++++ docs/README | 49 +++++++++++++++++++++++++++ docs/gettingstarted/writingdocs/gitreview.rst | 22 ++++++------ 4 files changed, 81 insertions(+), 11 deletions(-) create mode 100644 docs/Makefile create mode 100644 docs/README diff --git a/.gitignore b/.gitignore index 28f54a384b9..612efd4eab0 100644 --- a/.gitignore +++ b/.gitignore @@ -84,6 +84,7 @@ GTAGS /build-root/.doxygen-siphon.dep /docs/_build /env +!/docs/Makefile # indent backup files *.BAK diff --git a/docs/Makefile b/docs/Makefile new file mode 100644 index 00000000000..60e4b90b94a --- /dev/null +++ b/docs/Makefile @@ -0,0 +1,20 @@ +# Minimal makefile for Sphinx documentation +# + +# You can set these variables from the command line. +SPHINXOPTS = +SPHINXBUILD = sphinx-build +SPHINXPROJ = fdio-firstcut +SOURCEDIR = . +BUILDDIR = _build + +# Put it first so that "make" without argument is like "make help". +help: + @$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) + +.PHONY: help Makefile + +# Catch-all target: route all unknown targets to Sphinx using the new +# "make mode" option. $(O) is meant as a shortcut for $(SPHINXOPTS). +%: Makefile + @$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) \ No newline at end of file diff --git a/docs/README b/docs/README new file mode 100644 index 00000000000..d9a70912edb --- /dev/null +++ b/docs/README @@ -0,0 +1,49 @@ + +Building VPP Documents + +These instructions show how the VPP documentation sources are built. + +To build your files, you can either Create a Virtual Environment using +virtualenv, which installs all the required applications for you. + +Create a Virtual Environment using virtualenv +============================ + +For more information on how to use the Python virtual environment check +out https://packaging.python.org/guides/installing-using-pip-and-virtualenv + +Get the Documents +------------------------------ + +For example start with a clone of the vpp. + +$ git clone https://gerrit.fd.io/r/vpp +$ cd vpp + +Install the virtual environment +---------------------------------------------- + +$ python -m pip install --user virtualenv +$ python -m virtualenv env +$ source env/bin/activate +$ pip install -r docs/etc/requirements.txt +$ cd docs + +Which installs all the required applications into it's own, isolated, +virtual environment, so as to not interfere with other builds that may +use different versions of software. + +Build the html files +---------------------------- + +Be sure you are in your vpp/docs directory, since that is where Sphinx will +look for your conf.py file, and build the documents into an index.html file + +$ make html + +View the results +------------------------ + +If there are no errors during the build process, you should now have an +index.html file in your vpp/docs/_build/html directory, which you can +then view in your browser. diff --git a/docs/gettingstarted/writingdocs/gitreview.rst b/docs/gettingstarted/writingdocs/gitreview.rst index 63916e1d752..308e313460b 100644 --- a/docs/gettingstarted/writingdocs/gitreview.rst +++ b/docs/gettingstarted/writingdocs/gitreview.rst @@ -39,24 +39,24 @@ To get a new patch reviewed use the following: .. code-block:: console - git status - git add - git commit -s - git review + $ git status + $ git add + $ git commit -s + $ git review If the patch is a draft use the following: .. note:: - git review -D + $ git review -D To get back to the master: .. code-block:: console - git reset --hard origin/master - git checkout master + $ git reset --hard origin/master + $ git checkout master Existing patch -------------- @@ -66,7 +66,7 @@ To modify an existing patch: .. code-block:: console - git status - git add - git commit --amend - git review + $ git status + $ git add + $ git commit --amend + $ git review -- 2.16.6