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.
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!