[Bf-docboard-svn] bf-manual: [8150] trunk/blender_docs: Makefiles: Make default target livehtml
Aaron Carlisle
noreply at blender.org
Tue Jun 22 01:13:02 CEST 2021
Revision: 8150
https://developer.blender.org/rBM8150
Author: Blendify
Date: 2021-06-22 01:13:02 +0200 (Tue, 22 Jun 2021)
Log Message:
-----------
Makefiles: Make default target livehtml
This is a change that makes it easier to build and view the docs
Writes may want to run `pip install -r requirements --upgrade`
if they dont have the autobuild extension.
This commit also updates the documentation to reflect the changes.
Modified Paths:
--------------
trunk/blender_docs/Makefile
trunk/blender_docs/make.bat
trunk/blender_docs/manual/about/contribute/build/linux.rst
trunk/blender_docs/manual/about/contribute/build/macos.rst
trunk/blender_docs/manual/about/contribute/build/windows.rst
Modified: trunk/blender_docs/Makefile
===================================================================
--- trunk/blender_docs/Makefile 2021-06-19 01:33:25 UTC (rev 8149)
+++ trunk/blender_docs/Makefile 2021-06-21 23:13:02 UTC (rev 8150)
@@ -49,7 +49,7 @@
else ifneq "$(findstring latexpdf, $(MAKECMDGOALS))" ""
.DEFAULT_GOAL := latexpdf
else
- .DEFAULT_GOAL := html
+ .DEFAULT_GOAL := livehtml
endif
@@ -75,14 +75,8 @@
livehtml:
@QUICKY_CHAPTERS=$(QUICKY_CHAPTERS) \
- sphinx-autobuild --open-browser --delay 0 "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+ sphinx-autobuild --open-browser --delay 0 "$(SOURCEDIR)" "$(BUILDDIR)/html" $(SPHINXOPTS) $(O)
-html: .SPHINXBUILD_EXISTS
- @QUICKY_CHAPTERS=$(QUICKY_CHAPTERS) \
- $(SPHINXBUILD) -M html "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
- @echo "To view, run:"
- @echo " "$(OPEN_CMD) $(shell pwd)"/$(BUILDDIR)/html/$(CONTENTS_HTML)"
-
latexpdf: .SPHINXBUILD_EXISTS
@QUICKY_CHAPTERS=$(QUICKY_CHAPTERS) \
$(SPHINXBUILD) -M latexpdf "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
@@ -135,7 +129,7 @@
@echo "=============="
@echo "Convenience targets provided for building docs"
@echo ""
- @echo "- livehtml to auto build on file changes on host on localhost"
+ @echo "- livehtml (default) to auto build on file changes and host on localhost"
@echo "- epubpdf to convert an epub file to pdf"
@echo "- readme to make a 'readme.html' file"
@echo "- clean to delete all old build files"
Modified: trunk/blender_docs/make.bat
===================================================================
--- trunk/blender_docs/make.bat 2021-06-19 01:33:25 UTC (rev 8149)
+++ trunk/blender_docs/make.bat 2021-06-21 23:13:02 UTC (rev 8150)
@@ -33,9 +33,9 @@
:sphinx_ok
-REM Default to HTML
+REM Default to livehtml
if "%1" == "" (
- goto html
+ goto livehtml
)
if "%1" == "help" (
@@ -48,7 +48,7 @@
echo.==============
echo.Convenience targets provided for building docs
echo.
- echo.- livehtml to auto build on file changes on host on localhost
+ echo.- livehtml (default) to auto build on file changes and host on localhost
echo.- readme to make a 'readme.html' file
echo.- clean to delete all old build files
echo.
@@ -68,20 +68,12 @@
)
if "%1" == "livehtml" (
- sphinx-autobuild --open-browser --delay 0 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
+ :livehtml
+ sphinx-autobuild --open-browser --delay 0 %SOURCEDIR% %BUILDDIR%/html %SPHINXOPTS% %O%
if errorlevel 1 exit /b 1
goto EOF
)
-if "%1" == "html" (
- :html
- %SPHINXBUILD% -b html %SPHINXOPTS% %O% %SOURCEDIR% %BUILDDIR%/html
- if errorlevel 1 exit /b 1
- echo.To view, run:
- echo. start %BUILDDIR%/html/index.html
- goto EOF
-)
-
if "%1" == "latexpdf" (
%SPHINXBUILD% -b latex %SPHINXOPTS% %O% %SOURCEDIR% %BUILDDIR%/latex
cd %BUILDDIR%/latex
Modified: trunk/blender_docs/manual/about/contribute/build/linux.rst
===================================================================
--- trunk/blender_docs/manual/about/contribute/build/linux.rst 2021-06-19 01:33:25 UTC (rev 8149)
+++ trunk/blender_docs/manual/about/contribute/build/linux.rst 2021-06-21 23:13:02 UTC (rev 8150)
@@ -4,24 +4,27 @@
Building on Linux
*****************
-Converting the RST-files into pretty HTML pages.
+Converting the RST-files into pretty HTML pages is simple.
Open a terminal to the folder ``~/blender_docs`` and simply run::
make
-This is the command you will always use when building the docs.
-The building process may take several minutes the first time (or after any major changes),
-but the next time you build it should only take a few seconds.
+This is the command you should always use when building the docs,
+however, other commands are avaible by typing ``make help``.
+This command will convert the RST-files into HTML pages
+and automaticlly open your default web browser to view the result.
+The command will continue to run and watch for changes made to the RST-files
+and refresh the HTML pages as necessary.
+.. tip::
-Viewing the Local Manual
-========================
+ The converted pages can also be viewed manually by browsing the build directory: ``~/blender_docs/build/html``.
+ For example to open the home page, open :file:`build/html/index.html` to read the manual.
-Once the docs have been built, all the HTML files can be found inside ``~/blender_docs/build/html``.
-Try opening ``build/html/index.html`` in your web browser and read the manual::
- xdg-open build/html/index.html
+The building process may take several minutes the first time (or after any major changes),
+but for subsequent changes it should only take a few seconds.
Now that you are able to build the manual, the next paragraph is about an optional quick build.
@@ -33,8 +36,8 @@
make <chapter name>
-For example, to build only the documentation for the modifiers, use ``make modifiers``.
-You can then view this quick build by opening ``build/html/contents_quicky.html``.
+For example, to build only the documentation for the modifiers, use ``make modeling``.
+You can then view this quick build by opening :file:`build/html/contents_quicky.html`.
This will build very quickly, but it will mean your next complete build of all the chapters will be slow.
Modified: trunk/blender_docs/manual/about/contribute/build/macos.rst
===================================================================
--- trunk/blender_docs/manual/about/contribute/build/macos.rst 2021-06-19 01:33:25 UTC (rev 8149)
+++ trunk/blender_docs/manual/about/contribute/build/macos.rst 2021-06-21 23:13:02 UTC (rev 8150)
@@ -4,24 +4,27 @@
Building on macOS
*****************
-Converting the RST-files into pretty HTML pages.
+Converting the RST-files into pretty HTML pages is simple.
Open a terminal to the folder ``~/blender_docs`` and simply run::
make
-This is the command you will always use when building the docs.
-The building process may take several minutes the first time (or after any major changes),
-but the next time you build it should only take a few seconds.
+This is the command you should always use when building the docs,
+however, other commands are avaible by typing ``make help``.
+This command will convert the RST-files into HTML pages
+and automaticlly open your default web browser to view the result.
+The command will continue to run and watch for changes made to the RST-files
+and refresh the HTML pages as necessary.
+.. tip::
-Viewing the Local Manual
-========================
+ The converted pages can also be viewed manually by browsing the build directory: ``~/blender_docs/build/html``.
+ For example to open the home page, open :file:`build/html/index.html` to read the manual.
-Once the docs have been built, all the HTML files can be found inside ``~/blender_docs/build/html``.
-Try opening ``build/html/index.html`` in your web browser and read the manual::
- open build/html/index.html
+The building process may take several minutes the first time (or after any major changes),
+but for subsequent changes it should only take a few seconds.
Now that you are able to build the manual, the next paragraph is about an optional quick build.
@@ -33,8 +36,8 @@
make <chapter name>
-For example, to build only the documentation for the modifiers, use ``make modifiers``.
-You can then view this quick build by opening ``build/html/contents_quicky.html``.
+For example, to build only the documentation for the modifiers, use ``make modeling``.
+You can then view this quick build by opening :file:`build/html/contents_quicky.html`.
This will build very quickly, but it will mean your next complete build of all the chapters will be slow.
Modified: trunk/blender_docs/manual/about/contribute/build/windows.rst
===================================================================
--- trunk/blender_docs/manual/about/contribute/build/windows.rst 2021-06-19 01:33:25 UTC (rev 8149)
+++ trunk/blender_docs/manual/about/contribute/build/windows.rst 2021-06-21 23:13:02 UTC (rev 8150)
@@ -4,46 +4,40 @@
Building on Windows
*******************
-Converting the RST-files into pretty HTML pages.
+Converting the RST-files into pretty HTML pages is simple.
+
There are two ways to run the build process.
-
.. rubric:: File browser
-Run ``make.bat`` in the ``C:\blender_docs`` folder.
+Open :file:`make.bat` in the ``C:\blender_docs`` folder.
-.. tip::
+.. rubric:: Command prompt
- Create a desktop shortcut to ``make``.
+#. Or open the command prompt and change to the repository with ``cd C:\blender_docs``.
+#. Build using the following command
+::
-.. rubric:: Command prompt
-
-#. Or open a command prompt and change to the repository with ``cd C:\blender_docs``.
-#. Build using the following command::
-
make
-The building process may take several minutes the first time (or after any major changes),
-but the next time you build it should only take a few seconds.
+This is the command you should always use when building the docs,
+however, other commands are avaible by typing ``make help``.
+This command will convert the RST-files into HTML pages
+and automaticlly open your default web browser to view the result.
+The command will continue to run and watch for changes made to the RST-files
+and refresh the HTML pages as necessary.
-.. note::
+.. tip::
- If you encounter an error ending with ``TypeError: an integer is required (got type str)``,
- you may need to install an older version of *Babel* (the Python Internationalization Library).
+ The converted pages can also be viewed manual by browsing the build directory: ``~/blender_docs/build/html``.
+ For example to open the home page, open :file:`build/html/index.html` to read the manual.
- To do this, simply run::
- pip install sphinx "babel<2.0"
+The building process may take several minutes the first time (or after any major changes),
+but for subsequent changes it should only take a few seconds.
-Viewing the Local Manual
-========================
-
-Once the docs have been built, all the HTML files can be found inside ``C:\blender_docs\build\html``.
-Try opening ``\build\html\index.html`` in your web browser and read the manual.
-
-
------------------------
Continue with the next step: :doc:`Editing </about/contribute/editing>`.
More information about the Bf-docboard-svn
mailing list