Finally Fixing the Little Docs Glitches in Hive-Nectar and NectarEngine

This one is not a huge feature announcement.

No grand architectural rewrite.

Just one of those small, annoying maintenance jobs that had been bothering me for a while, and finally got fixed.

I cleaned up the generated documentation for hive-nectar and nectarengine.

If you have ever worked on an older Python library that has moved through a few different packaging eras, you probably know the kind of thing I mean. The code works. The package installs. The tests are fine. But some little piece of documentation tooling is still carrying assumptions from the previous layout, and every time you look at it you think:

I should really fix that.

Then you do five other things instead.

The Background

hive-nectar started life as a fork of beem, then gradually became my modernized Hive SDK.

That means it has some history.

Some of that history is useful. Some of it is just old scaffolding that survived because it was not actively hurting anything.

At some point during the modernization work, the Python source moved into a proper src/ layout:

src/nectar
src/nectarapi
src/nectarbase
src/nectargraphenebase
src/nectarstorage

That is the right shape for a modern Python package.

The problem was that the Sphinx documentation generation was still acting like the old repository layout was the real source of truth.

So the docs technically built, but the sidebar looked wrong.

Instead of presenting the API reference as the actual package modules, the generated documentation had this ugly top-level src entry sitting in the navigation.

That is not catastrophic.

But it is sloppy.

And it had been bothering me.

The Same Bug in Two Places

Once I fixed it in hive-nectar, I switched over to nectarengine and found the same issue there.

That makes sense. nectarengine is the Hive-Engine side module, and it went through a similar modernization path.

The pattern was basically identical:

sphinx-apidoc -d 4 -e -f -o docs ./src *.py tests

That command worked, but it caused sphinx-apidoc to treat src as the thing being documented.

So the generated modules.rst started with:

src
===

Which is not what I wanted users to see.

The code lives under src.

The public API does not.

The public API is nectar, nectarapi, nectarbase, nectarengine, and the other real packages.

The Fix

The fix was not complicated, but it needed to be done.

For hive-nectar, I changed the docs target so it regenerates the API reference from the src layout while giving the generated module index a proper heading:

uv run sphinx-apidoc -H "API Reference" -d 4 -e -f -o docs src
rm -rf docs/_build/html docs/_build/doctrees
uv run sphinx-build -b html docs docs/_build/html

That turned the sidebar from src into API Reference, which is what it should have been all along.

While I was there, I also cleaned up stale generated files that pointed at modules that no longer exist, like old hivesigner and nectargrapheneapi references.

Those are the kind of leftovers that make old docs feel haunted by previous versions of the codebase.

nectarengine got the same treatment, plus a small Sphinx config cleanup:

• explicitly include ../src in docs/conf.py
• use language = "en" instead of uppercase EN
• stop warning about a missing _static directory

Nothing dramatic.

Just the docs being made to reflect the package that actually exists now.

Read the Docs

One thing I checked afterward was whether this needed a .readthedocs.yaml change.

Read the Docs does not run my make docs target directly. It runs Sphinx using the committed documentation files:

sphinx:
  configuration: docs/conf.py

So for now, this approach is fine.

The generated .rst API files are committed, and Read the Docs builds from those.

Long term, I may wire in a proper pre-build step so Read the Docs regenerates the API stubs automatically. But for these repos, the current workflow is good enough: run make docs, commit the generated docs, and let Read the Docs build the result.

That matches how these projects have already been maintained.

Why This Matters

This is not the kind of change that makes anyone rush to upgrade.

But it matters anyway.

Documentation is part of the user interface of a library.

If the docs sidebar looks like an internal directory dump, it sends the wrong signal. It makes the project feel less cared for than it actually is.

And in this case, the codebase has had a lot of care put into it:

• modern packaging
• uv workflows
• better HTTP handling
• cleaner Hive and Hive-Engine API layers
• ongoing dependency cleanup
• better type hints and tests

The docs should not be the part still wearing the old clothes.

Final Thoughts

The fixes are now committed in both repos.

• https://hive-nectar.readthedocs.io/en/latest/
• https://nectarengine.readthedocs.io/en/latest/

Small fix.

Big relief.

Sometimes maintenance is just finally sanding down the rough edges you have been looking at for months.

As always,
Michael Garcia a.k.a. TheCrazyGM

Edit: added links to readthedocs for both.