Building Sphinx Docs

[Byron]

I am using a clone of this repository at fb6f791
When trying to build the docs, I ran into the following issues:

• A Makefile is missing
  • Without a makefile, the primary makefile in the project root will fail when trying to make docs
  • Generating the makefile using sphinx-quickstart is a bit of a workaround as conf.py and index.rst need to be renamed temporarily, as quickstart refuses to work on existing files (or just use them).
  • Maybe it would already be enough to use the actual commandline ( sphinx-build -b html -d _build/doctrees . _build/html ) in the root makefile instead of referencing the non-existing sphinx-generated Makefile.
• Local references to files
  • in docs there is a symlink to a local file
  • in docs/_ext/bulbsdoc.py is a hardcoded local path

Maybe there are more issues further down the road, the ones mentioned are the ones I ran into so far.

Do you think it is possible to check-in the referenced local files to the project and use relative paths instead ?

Thanks You

[espeed]

Hi -

The docs are all online at http://bulbflow.com/docs -- the makefile and custom Sphinx extension were used to build them, and they wouldn't be meaningful anywhere else. I included the docs in the GitHub repo so that their versions tracked the code revisions. Do you need to recreate them internally somewhere?

[Byron]

Yes, I wanted to create the docs myself, but didn't expect them to be personalized due to the public nature of the project.
Maybe one could apply just a few little tweaks to allow everyone to build the docs, which would open them up for community amendments as well.
I believe it would be an advantage.

[espeed]

Bulbs 0.4 will make docs updatable by the community.