piecash icon indicating copy to clipboard operation
piecash copied to clipboard

Host Documentation Locally

Open flywire opened this issue 3 years ago • 8 comments

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",
]```

flywire avatar Jun 12 '21 06:06 flywire

Missing requirements:

pip install sphinxcontrib-programoutput

flywire avatar Jun 12 '21 07:06 flywire

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

flywire avatar Jun 12 '21 07:06 flywire

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)

sdementen avatar Jun 12 '21 08:06 sdementen

  • 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.

flywire avatar Jun 12 '21 09:06 flywire

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

flywire avatar Jun 12 '21 09:06 flywire

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 .

sdementen avatar Jun 12 '21 10:06 sdementen

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

flywire avatar Jun 12 '21 10:06 flywire

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

flywire avatar Jun 13 '21 03:06 flywire