Rendering the docs. Pages locally and Seeing Changes before Asking for a Merge Request...

General Discussion
1

Yeppers,

Me again…I seem to be asking a lot lately. Anyway, I am asking a lot here too. I would like an explanation on docs.

I want to render them locally so I can see the exact difference in change before actually creating a merge request. Is this possible for local networking and building of the pages…

I looked online at git.beagleboard.org and the changes are there locally at their online site.

The issue so far is that I cannot see the graphics or colorful change of doc. scripts, “wording,” and/or “English” ideas I put into text…

Seth

P.S. If you have built the docs. locally and been able to display your changes, I am asking that you step up and let me know how in fact this may be done… Thank you.

2

Your guess is as good as mine.

$ git clone https://git.beagleboard.org/docs/docs.beagleboard.io.git

step into

$ cd docs.beagleboard.io

$ make html

:~/hdd1/archive/git-clones/docs.beagleboard.io$ make
Sphinx v6.2.1
Please use `make target' where target is one of
  html        to make standalone HTML files
  dirhtml     to make HTML files named index.html in directories
  singlehtml  to make a single large HTML file
  pickle      to make pickle files
  json        to make JSON files
  htmlhelp    to make HTML files and an HTML help project
  qthelp      to make HTML files and a qthelp project
  devhelp     to make HTML files and a Devhelp project
  epub        to make an epub
  latex       to make LaTeX files, you can set PAPER=a4 or PAPER=letter
  latexpdf    to make LaTeX and PDF files (default pdflatex)
  latexpdfja  to make LaTeX files and run them through platex/dvipdfmx
  text        to make text files
  man         to make manual pages
  texinfo     to make Texinfo files
  info        to make Texinfo files and run them through makeinfo
  gettext     to make PO message catalogs
  changes     to make an overview of all changed/added/deprecated items
  xml         to make Docutils-native XML files
  pseudoxml   to make pseudoxml-XML files for display purposes
  linkcheck   to check all external links for integrity
  doctest     to run all doctests embedded in the documentation (if enabled)
  coverage    to run coverage check of the documentation (if enabled)
  clean       to remove everything in the build directory

This is what I get, not sure where the module is missing from the tree or my box…

Running Sphinx v6.2.1
Warning: Could not extract docs version
Warning: Could not extract pages information

Extension error:
Could not import extension sphinxcontrib.rsvgconverter (exception: No module named 'sphinxcontrib.rsvgconverter')
make: *** [Makefile:20: html] Error 2

Here is one of the missing modules

pip install sphinxcontrib-svg2pdfconverter

At this point I am done with this, sorry I was not of much help.

1 Like
3

Hello @foxsquirrel ,

Thank you. I will test this idea soon and keep trying to display graphics along w/ text soon w/ this building of ideas.

Seth

1 Like
4

Hello,

No issue. I tried the build…instead of just gathering momentum. I am busted on the conf.py file b/c of pip3 and an install that is needed…

  1. pipx is a thing now…
  2. helpful to me so far, no.
  3. –break-system-packages … yes. Blah.

This is w/ a couple installed pip3 or pipx venv “understandings…” I mean here are my errors…

Running Sphinx v5.3.0

Configuration error:
There is a programmable error in your configuration file:

Traceback (most recent call last):
  File "/usr/lib/python3/dist-packages/sphinx/config.py", line 350, in eval_config_file
    exec(code, namespace)
  File "/home/serf/docs.beagleboard.io/conf.py", line 11, in <module>
    import sphinx_rtd_theme
ModuleNotFoundError: No module named 'sphinx_rtd_theme'

make: *** [Makefile:20: html] Error 2

Anyway…

Thank you for the update.

Seth

P.S. PEP 668 is what I will research for a bit. If anyone else is researching this idea, please jump on in!

I have been reading and trying to find packages…

Update

Since the package research for this build, I am stuck on sphinx_design so far.

I cannot find the right build for it. Send rations!

5

Myself, I would be moving on.

My recommendation is this, buy a hole punch, 3 ring binders, some page dividers and make your own manuals. I have plenty of binders with information and notes, all of it will be donated to the national archives a/k/a county landfill when I am gone. In the mean time it seems the best way to go if you cannot find a .pdf or can download part of the website. You can use wget and with the correct settings have the links point back to your hdd then you just open it up in a web browser for offline viewing.

1 Like
6

Perfect Timing,

I guess I may keep trying. It is undoubtedly up to me for now. If things get too difficult for the likes of just me, I may say kaput to it…

Notes are good. I take 'em w/ stride. Thank you for your words. New insight!

Seth

P.S. Although it is insightful to hear from other people, the guidance is not always there and then the cycle begins.

1 Like
7

Might look into cherrytree. The developer has current .deb on their page, the apt is pretty old.

https://www.giuspen.net/cherrytree/
It is a good way to take notes, you can even enter bash script and run from your doc. Believe it will do much more just need to spend some time with it.

I also use it with git so I can clone all my docs onto a new machine and push new contribution to the server, it works really well, just don’t plan on doing any thing that manipulates the plain text(git functionality).

8

If it has a hand font of my nature, I am in!

Seth