Bug 411 - set up sphinx for all repos and upload to website
Summary: set up sphinx for all repos and upload to website
Status: CONFIRMED
Alias: None
Product: Libre-SOC Website
Classification: Unclassified
Component: website (show other bugs)
Version: unspecified
Hardware: Other Linux
: --- enhancement
Assignee: Alain D D Williams
URL:
Depends on:
Blocks:
 
Reported: 2020-07-02 00:55 BST by Luke Kenneth Casson Leighton
Modified: 2020-07-29 18:44 BST (History)
2 users (show)

See Also:
NLnet milestone: ---
total budget (EUR) for completion of task and all subtasks: 0
budget (EUR) for this task, excluding subtasks' budget: 0
parent task for budget allocation:
child tasks for budget allocation:
The table of payments (in EUR) for this task; TOML format:


Attachments

Note You need to log in before you can comment on or make changes to this bug.
Description Luke Kenneth Casson Leighton 2020-07-02 00:55:55 BST
sphinx is a standard way to do documentaion including python code. nmigen has a nice style that can be used as a base, plus also link to it.

one option is docs.libre-soc.org, another is libre-soc.org/docs.
Comment 1 Jacob Lifshay 2020-07-02 01:05:22 BST
We could also have a spot for hosting the rust docs for kazan and other rust libraries/programs. Also, we would want to have autogenerated python documentation for our rust libraries that have python bindings. If sphinx can't handle loading a python extension library then documenting it, we could use pdoc3, which is what I used to generate the python API docs for simple-soft-float.
Comment 3 Luke Kenneth Casson Leighton 2020-07-02 01:16:56 BST
(In reply to Jacob Lifshay from comment #1)
> We could also have a spot for hosting the rust docs for kazan and other rust
> libraries/programs.

ah good idea.

> Also, we would want to have autogenerated python
> documentation for our rust libraries that have python bindings.

yes.  as long as they all have docstrings this should work fine.

> If sphinx
> can't handle loading a python extension library then documenting it, we
> could use pdoc3, which is what I used to generate the python API docs for
> simple-soft-float.

i love epydoc.  it's the first of the docstring extractors.  sigh :)  except the html it generates burns your eyes with primary colours.

sphinx's autodoc feature looks like someone caught optionitis.  tracking down good examples there would be handy rather than spending days trying to read all the options
Comment 4 Luke Kenneth Casson Leighton 2020-07-02 03:14:21 BST
https://www.sphinx-doc.org/en/1.8/usage/extensions/napoleon.html#module-sphinx.ext.napoleon

rst is pretty illeligble in docstrings.  this helps.
Comment 5 Luke Kenneth Casson Leighton 2020-07-02 03:25:03 BST
https://www.sphinx-doc.org/en/1.8/usage/extensions/extlinks.html

useful for shortening bugtracker links
Comment 6 Luke Kenneth Casson Leighton 2020-07-02 03:33:12 BST
https://medium.com/@eikonomega/getting-started-with-sphinx-autodoc-part-1-2cebbbca5365

seems to be quite good start
Comment 8 Luke Kenneth Casson Leighton 2020-07-02 13:50:45 BST
i have docs.libre-soc.org set up in prototype form.  it needs review.
Comment 9 Jacob Lifshay 2020-07-02 19:59:13 BST
(In reply to Luke Kenneth Casson Leighton from comment #8)
> i have docs.libre-soc.org set up in prototype form.  it needs review.

it currently redirects to bugs.libre-soc.org
Comment 10 Luke Kenneth Casson Leighton 2020-07-26 20:48:31 BST
alain i found /var/www/acme/SSLConfigs/libre-soc.org.cnf
and added docs.libre-soc.org - it _should_ if i am reading
things correctly be possible to run RenewCertificates
and that should be that?
Comment 11 Alain D D Williams 2020-07-29 18:19:43 BST
Everything looks OK

You did not run bin/CreateSigningRequests

Then bin/CheckSiteAccess ... which would have shown the problem:

The DNS name docs.libre-riscv.org does not return anything

Set that up & I will do the rest.


There is a write up here:
https://www.phcomp.co.uk/Tutorials/Web-Technologies/Configure-Lets-Encrypt-with-acme_tiny.html
Comment 12 Luke Kenneth Casson Leighton 2020-07-29 18:44:04 BST
(In reply to Alain D D Williams from comment #11)
> Everything looks OK
> 
> You did not run bin/CreateSigningRequests

ahh ok
 
> Then bin/CheckSiteAccess ... which would have shown the problem:
> 
> The DNS name docs.libre-riscv.org does not return anything

removed it.

> Set that up & I will do the rest.

just to be obtuse and because i wanted to get it right maaaybe just the once
i ran it to see what would happen

> 
> There is a write up here:
> https://www.phcomp.co.uk/Tutorials/Web-Technologies/Configure-Lets-Encrypt-
> with-acme_tiny.html

cool!