Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We鈥檒l occasionally send you account related emails.

Already on GitHub? Sign in to your account

Add the sphinx documentation generator to the documentation we already have #2343

Merged
merged 5 commits into from Feb 18, 2019

Conversation

Projects
None yet
4 participants
@cdecker
Copy link
Member

cdecker commented Feb 11, 2019

I thought it might be nice to have a browsable (and printable) version of the documentation in an easy to find place. Since we already have quite some documentation in markdown, I decided to give sphinx a shot. It's a documentation generator that is popular with the python community, and is not to be confused with the onion routing packet protocol 馃槈

This PR just puts all the pieces in place for sphinx to generate the rendered documents as HTML and PDF.

The resulting documentation is automatically built and published on every commit to master here https://lightning.readthedocs.io/ which is a nice place we can refer users to, and I plan to write an FAQ as well, so we can cut down on the recurring questions.

cdecker added some commits Feb 8, 2019

docs: Consolidating header hierarchy slightly
This is a preparatory step for the automatic documentation generation
that is going to use `sphinx-doc`. Each document should include a top
level header that matches the name and scope of the document and all
following headers should be of a lower level than the top-level
header.

Signed-off-by: Christian Decker <decker.christian@gmail.com>
docs: Add configuration for the sphinx documentation generator
This just takes the existing documentation, and generates a nice HTML
version we can point users to. The documentation is automatically
generated on every commit to `master` and will be deployed here:

https://lightning.readthedocs.io/

Signed-off-by: Christian Decker <decker.christian@gmail.com>
readme: Add a readthedocs badge to show that we have nice docs :-)
Signed-off-by: Christian Decker <decker.christian@gmail.com>
docs: Fix two permanent redirects
Courtesy of `sphinx-build -b linkchecker doc`

Signed-off-by: Christian Decker <decker.christian@gmail.com>

@cdecker cdecker added the docs label Feb 11, 2019

@cdecker cdecker self-assigned this Feb 11, 2019

@cdecker cdecker requested a review from rustyrussell Feb 11, 2019

doc: add configure --enable-dev in testing chapter
As a newbie, I forgot to re-enable the dev options that are required to run the tests...
@rustyrussell

This comment has been minimized.

Copy link
Contributor

rustyrussell commented on doc/conf.py in 064fde1 Feb 14, 2019

Can we extract these? We currently calculate it in multiple places, perhaps we can generate a version.conf file or something (we could use config.vars but that means running configure all the time?)

This comment has been minimized.

Copy link
Member Author

cdecker replied Feb 14, 2019

These can absolutely be extracted, after all this is just python code, so we could call git here :-)

@rustyrussell

This comment has been minimized.

Copy link
Contributor

rustyrussell commented on 064fde1 Feb 14, 2019

Any chance we can tie our man pages in here too? The lightning-config is particularly enlightening. If necessary we could change the source format?

This comment has been minimized.

Copy link
Member Author

cdecker replied Feb 14, 2019

I was looking at how we can include asciidoc document in there, but couldn't find a converter yet.

This comment has been minimized.

Copy link
Contributor

arowser replied Feb 15, 2019

@rustyrussell
Copy link
Contributor

rustyrussell left a comment

Ack 117024f

@rustyrussell rustyrussell merged commit 3db5345 into master Feb 18, 2019

3 checks passed

ackbot PR ack'd by rustyrussell
continuous-integration/travis-ci/pr The Travis CI build passed
Details
continuous-integration/travis-ci/push The Travis CI build passed
Details
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
You can鈥檛 perform that action at this time.