Bug 634 - sphinx - build, install and interface with projects
Summary: sphinx - build, install and interface with projects
Status: RESOLVED FIXED
Alias: None
Product: Libre-SOC's first SoC
Classification: Unclassified
Component: Documentation (show other bugs)
Version: unspecified
Hardware: PC Linux
: --- normal
Assignee: vklr@vkten.in
URL:
Depends on:
Blocks:
 
Reported: 2021-04-29 17:13 BST by vklr@vkten.in
Modified: 2021-09-19 01:54 BST (History)
2 users (show)

See Also:
NLnet milestone: NLNet.2019.10.Wishbone
total budget (EUR) for completion of task and all subtasks: 150
budget (EUR) for this task, excluding subtasks' budget: 150
parent task for budget allocation: 384
child tasks for budget allocation:
The table of payments (in EUR) for this task; TOML format:
veera={amount=150,paid=2021-08-21}


Attachments

Note You need to log in before you can comment on or make changes to this bug.
Description vklr@vkten.in 2021-04-29 17:13:15 BST
sphinx - Needed for production of html, pdf and other format documentations.

* Instructions for build, install and interface with projects.

* TODO - nmutil, ieee754fpu, dev-env-setup build scripts  DONE

* TODO - Add to Makefile to produce html docs. DONE

* TODO - Add the generated html docs to website.
Comment 1 Luke Kenneth Casson Leighton 2021-04-29 22:41:57 BST
veera these were quick notes. i have added sphinx to the soc Makefile, the same thing needs to be added to nmutil and ieee754fpu.

you also have to copy over conf.py from soc and edit it accordingly ("Documentation for nmutil" not "documentation for SOC").

then if you look at http://libre-soc.org/docs you will see there are hyperlinks to docs.libre-soc.org locations.

the upload locations in the Makefiles need to match.

plus, you will see an "intersphinx" in the soc conf.py, nmutil and ieee754fpu need to be added to it.
Comment 2 vklr@vkten.in 2021-06-04 21:14:15 BST
Added and setup the sphinx for nmutil.

1) Added conf.py and index.rst

2) Setup Makefile for sphinx

Please review nmutil + sphinx.
Comment 3 vklr@vkten.in 2021-06-04 21:17:50 BST
Sphinx script for dev-env-script?

For nmutil, I used only:

apt-get install python3-sphinx python3-sphinx-rtd-theme python3-recommonmark

Do you wanna me add these to a install script in dev-env-script.git?

I will wait till ieee754fpu setup.
Comment 4 Luke Kenneth Casson Leighton 2021-06-04 22:10:24 BST
(In reply to vklr@vkten.in from comment #3)
> Sphinx script for dev-env-script?

> 
> For nmutil, I used only:
> 
> apt-get install python3-sphinx python3-sphinx-rtd-theme python3-recommonmark

that is probably enough

> Do you wanna me add these to a install script in dev-env-script.git?

the main dependencies one yes please, they are global in nature
to the install-hdl-reqs one

> I will wait till ieee754fpu setup.
Comment 5 vklr@vkten.in 2021-06-05 03:22:01 BST
Added and setup the sphinx for ieee754fpu.

1) Added conf.py and index.rst

2) Setup Makefile for sphinx

Please review ieee754fpu + sphinx.
Comment 6 vklr@vkten.in 2021-06-05 03:27:55 BST
Added sphinx dependencies to dev-env-setup/install-hdl-apt-reqs.

uri: https://git.libre-soc.org/?p=dev-env-setup.git;a=blob;f=install-hdl-apt-reqs;h=9ef6dd5ef727eb79dadd38bbfdf0519c8eaba04c;hb=HEAD

Please review.
Comment 7 vklr@vkten.in 2021-06-05 03:36:06 BST
In both nmutil and ieee754fpu, the intersphinx path for nmigen is now fixed (probably: please check) in conf.py. This may have to be done in soc.git/conf.py also.


Please review.
Comment 8 Luke Kenneth Casson Leighton 2021-06-05 10:33:34 BST
https://docs.libre-soc.org/nmutil/src/gen/nmutil.html#module-nmutil.stageapi

looks really good.
Comment 10 vklr@vkten.in 2021-06-05 12:25:06 BST
(In reply to Luke Kenneth Casson Leighton from comment #9)
> 
> needs the links adding
> * https://docs.libre-soc.org/nmigen/
> * https://docs.libre-soc.org/ieee754fpu/
> 
> then i think we're done with this one.  good stuff.

Links added.