piecash
piecash copied to clipboard
Host Documentation Locally
How can I use this document offline?
Purpose:
-
Allow Documentation files to be viewed offline
-
Make edits to the docs themselves and render them locally so you can inspect changes before pushing back to the fork
Install:
-
Python V3
-
pip install Sphinx
-
pip install sphinx-autobuild
-
pip install sphinx-rtd-theme
-
Download repository from a fork of your choice and Unzip to a directory
Run:
Update: See https://github.com/sdementen/piecash/issues/175#issuecomment-860143220
Windows
-
Navigate to the directory in Explorer and on the address bar enter
make livehtml
to start the local server -
In your browser enter
http://127.0.0.1:8000
If you make any changes to the local User Manual files they will be updated in the browser.
../piecash/docs/makefile
# Minimal makefile for Sphinx documentation
#
# You can set these variables from the command line, and also
# from the environment for the first two.
SPHINXOPTS ?=
SPHINXBUILD ?= sphinx-build
SOURCEDIR = source
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)
../piecash/docs/make.bat
@ECHO OFF
pushd %~dp0
REM Command file for Sphinx documentation
if "%SPHINXBUILD%" == "" (
set SPHINXBUILD=sphinx-build
)
set SOURCEDIR=source
set BUILDDIR=build
if "%1" == "" goto help
if "%1" == "livehtml" (
sphinx-autobuild -b html %SOURCEDIR% %BUILDDIR%\html
goto end
)
%SPHINXBUILD% >NUL 2>NUL
if errorlevel 9009 (
echo.
echo.The 'sphinx-build' command was not found. Make sure you have Sphinx
echo.installed, then set the SPHINXBUILD environment variable to point
echo.to the full path of the 'sphinx-build' executable. Alternatively you
echo.may add the Sphinx directory to PATH.
echo.
echo.If you don't have Sphinx installed, grab it from
echo.http://sphinx-doc.org/
exit /b 1
)
%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
goto end
:help
%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
:end
popd
Install or disable any extensions that aren't installed. eg:
../piecash/docs/conf.py
extensions = [
"sphinx.ext.autodoc",
"sphinx.ext.intersphinx",
"sphinx.ext.todo",
"sphinx.ext.coverage",
"sphinx.ext.viewcode",
# "sphinxcontrib.napoleon",
# "IPython.sphinxext.ipython_console_highlighting",
# "IPython.sphinxext.ipython_directive",
# "sphinxcontrib.programoutput",
]```
Missing requirements:
pip install sphinxcontrib-programoutput
How are the following installed:
- IPython.sphinxext.ipython_console_highlighting
- IPython.sphinxext.ipython_directive
E:\source\repos\piecash\tests>pip install IPython.sphinxext.ipython_console_highlighting
ERROR: Could not find a version that satisfies the requirement IPython.sphinxext.ipython_console_highlighting (from versions: none)
ERROR: No matching distribution found for IPython.sphinxext.ipython_console_highlighting
E:\source\repos\piecash\tests>pip install IPython.sphinxext.ipython_directive
ERROR: Could not find a version that satisfies the requirement IPython.sphinxext.ipython_directive (from versions: none)
ERROR: No matching distribution found for IPython.sphinxext.ipython_directive
I think all this is taken care of when you install piecash in developer mode with "pip install -e ." when you are in the piecash root folder. Afterwards, the tests can be run with "python setup.py test" and the doc with "python setup.py build_doc" (not sure about the exact commands but they are the standard setup.py commands for tests and docs)
- to build the doc (do not forget to
pipenv install -e .[doc]
before)::cd docs make html
The documentation will be available through docs/build/html/index.html.
make livehtml
is not a normal build, it re-renders pages on on http://127.0.0.1:8000 whenever the source is changed, ie type-save-display.
I think all this is taken care of when you install piecash in developer mode with "pip install -e ."
Hmm, going back through my terminal I don't think so:
E:\source\repos>pip3 uninstall piecash
...
E:\source\repos>git clone https://github.com/flywire/piecash.git
Cloning into 'piecash'...
...
E:\source\repos>pip3 install -e E:\source\repos\piecash
https://github.com/sdementen/piecash/blob/master/DEVELOPER.rst
You're missing the final dot '.' in your pip command
On Sat, Jun 12, 2021, 11:23 flywire @.***> wrote:
I think all this is taken care of when you install piecash in developer mode with "pip install -e ."
Hmm, going back through my terminal I don't think so:
E:\source\repos>git clone https://github.com/flywire/piecash.git Cloning into 'piecash'... ... E:\source\repos>pip3 install -e E:\source\repos\piecash
— You are receiving this because you commented. Reply to this email directly, view it on GitHub https://github.com/sdementen/piecash/issues/175#issuecomment-860027071, or unsubscribe https://github.com/notifications/unsubscribe-auth/AAJ6S5WHHPIGNCOJKNN43U3TSMRQRANCNFSM46R7L7FQ .
I've been using it like that for at least a year with no problems. Issue is pages full of errors from no IPython.sphinxext.ipython*
https://github.com/sdementen/piecash/issues/175#issuecomment-860016235
After installing the missing extensions install https://pypi.org/project/sphinx-autobuild/
E:\source\repos\piecash\docs>sphinx-autobuild source docs/_build/html
[sphinx-autobuild] > sphinx-build 'E:\source\repos\piecash\docs\source' 'E:\source\repos\piecash\docs\docs\_build\html'
Running Sphinx v4.0.2
loading intersphinx inventory from http://docs.python.org/objects.inv...
intersphinx inventory has moved: http://docs.python.org/objects.inv -> https://docs.python.org/3/objects.inv
building [mo]: targets for 0 po files that are out of date
building [html]: targets for 32 source files that are out of date
updating environment: [new config] 32 added, 0 changed, 0 removed
c:\users\user\appdata\local\programs\python\python39\lib\site-packages\sqlalchemy\ext\declarative\api.py:210: SAWarning: Unmanaged access of declarative attribute address from non-mapped class Person
util.warn(
c:\users\user\appdata\local\programs\python\python39\lib\site-packages\sqlalchemy\ext\declarative\api.py:210: SAWarning: Unmanaged access of declarative attribute currency from non-mapped class Person
util.warn(
c:\users\user\appdata\local\programs\python\python39\lib\site-packages\sqlalchemy\ext\declarative\api.py:210: SAWarning: Unmanaged access of declarative attribute currency_guid from non-mapped class Person
util.warn(
reading sources... [100%] tutorial/index_new
E:\source\repos\piecash\piecash\core\account.py:docstring of piecash.core.account.Account.get_balance:15: WARNING: duplicate object description of piecash.core.account.Account.commodity, other instance in api/piecash.core.account, use :noindex: for one of them
looking for now-outdated files... none found
pickling environment... done
checking consistency... done
preparing documents... done
writing output... [100%] tutorial/index_new
generating indices... genindex py-modindex done
highlighting module code... [100%] piecash.sa_extra
writing additional pages... search done
copying images... [100%] schema.png
copying static files... done
copying extra files... done
dumping search index in English (code: en)... done
dumping object inventory... done
build succeeded, 1 warning.
The HTML pages are in docs\_build\html.
[I 210613 12:58:18 server:335] Serving on http://127.0.0.1:8000
[I 210613 12:58:18 handlers:62] Start watching changes
[I 210613 12:58:18 handlers:64] Start detecting changes
[I 210613 12:58:50 handlers:135] Browser Connected: http://127.0.0.1:8000/
[W 210613 12:58:50 web:2239] 404 GET /favicon.ico (127.0.0.1) 1.00ms