| Summary: | set up sphinx for all repos and upload to website | ||
|---|---|---|---|
| Product: | Libre-SOC Website | Reporter: | Luke Kenneth Casson Leighton <lkcl> |
| Component: | website | Assignee: | Alain D D Williams <addw> |
| Status: | CONFIRMED --- | ||
| Severity: | enhancement | CC: | libre-soc-bugs, programmerjake |
| Priority: | --- | ||
| Version: | unspecified | ||
| Hardware: | Other | ||
| OS: | Linux | ||
| 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: | ||
|
Description
Luke Kenneth Casson Leighton
2020-07-02 00:55:55 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. https://www.sphinx-doc.org/en/1.8/usage/extensions/autodoc.html?highlight=docstrings https://github.com/nmigen/nmigen/tree/master/docs (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 https://www.sphinx-doc.org/en/1.8/usage/extensions/napoleon.html#module-sphinx.ext.napoleon rst is pretty illeligble in docstrings. this helps. https://www.sphinx-doc.org/en/1.8/usage/extensions/extlinks.html useful for shortening bugtracker links https://medium.com/@eikonomega/getting-started-with-sphinx-autodoc-part-1-2cebbbca5365 seems to be quite good start looks really good: https://github.com/im-tomu/fomu-workshop/blob/master/docs/requirements.txt https://github.com/im-tomu/fomu-workshop/blob/master/docs/conf.py#L39-L47 i have docs.libre-soc.org set up in prototype form. it needs review. (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 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? 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 (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! |