[libre-riscv-dev] Merging Repositories and Auto-Generating Static Documentation

[libre-riscv-dev] Merging Repositories and Auto-Generating Static Documentation

[Yehowshua]

As Jacob mentioned earlier, I’m all in favor of merging nmutil, ieee754fpu <https://git.libre-soc.org/?p=ieee754fpu.git;a=summary>, and soc into one repository called soc.

Also, I’m working my way through the codebase and writing documentation. I strongly believe that the documentation should exist in the soc git repository itself so that anyone else who works with the docs only has to clone the git repository. This in fact seems fairly standard these days:

https://github.com/YosysHQ/nextpnr/tree/master/docs <https://github.com/YosysHQ/nextpnr/tree/master/docs>
https://github.com/SymbiFlow/prjtrellis/tree/master/docs <https://github.com/SymbiFlow/prjtrellis/tree/master/docs>
https://github.com/enjoy-digital/litex/tree/master/doc <https://github.com/enjoy-digital/litex/tree/master/doc>

If this is the case - it could be needlessly complex to try to pull these into the wiki directly. What we can do is have a static docs server at docs.libre-soc.org that builds upon every commit.

We can use python mkdocs or python sphinx or whatever.

This means that the wiki is not so much for documentation as it is for containing larger ideas about the Libre-SOC project itself.

Lastly, merging nmutil, ieee754fpu <https://git.libre-soc.org/?p=ieee754fpu.git;a=summary>, and soc into one repository called soc allows use to have one ./docs directory from which to build all documentation.

To merge these repositories is simple. Just copy ieee754fpu and nmutill into soc and modify the setup.py.

@Alain - how hard do you think it would be to setup a docs.libre-soc.org <http://docs.libre-soc.org/> subdomain?

Thoughts? Comments?

Yehowshua
_______________________________________________
libre-riscv-dev mailing list
libre-riscv-dev@lists.libre-riscv.org
http://lists.libre-riscv.org/mailman/listinfo/libre-riscv-dev

Re: [libre-riscv-dev] Merging Repositories and Auto-Generating Static Documentation

[Luke Kenneth Casson Leighton]

On Mon, May 4, 2020 at 3:13 AM Yehowshua <yimmanuel3@gatech.edu> wrote:
>
> As Jacob mentioned earlier, I’m all in favor of merging nmutil, ieee754fpu <https://git.libre-soc.org/?p=ieee754fpu.git;a=summary>, and soc into one repository called soc.

as i explained: this would unfortunately be a mistake that has
implications for NLNet, as well as sending a strong message that
nobody is welcome to use those independent libraries.

we need to focus on getting the code written.  reorganising the
codebase in this major way is a distraction.

> Thoughts? Comments?

we need to focus on developing the code.  this is a distraction.

we have only *fifteen weeks*.

l.

_______________________________________________
libre-riscv-dev mailing list
libre-riscv-dev@lists.libre-riscv.org
http://lists.libre-riscv.org/mailman/listinfo/libre-riscv-dev

Re: [libre-riscv-dev] Merging Repositories and Auto-Generating Static Documentation

[Luke Kenneth Casson Leighton]

yehowshua: i understand the desire to reorganise because it gives you a
reason to go over everything, and thus crystallises the code in your mind
as working knowledge.

i really appreciate that you made the decision, several months ago, to help
with funding instead of coding as it is a critical step in the process.

however as we have only 15 weeks is the worst possie time to carry out
major reorganising.

it is a major distraction even to discuss this. i estimate it will be about
a WEEK to complete including rewriting all tutorials, automated scripts,
all of which critically depend on the repo structure.

alain is currently focussing on designing the ISA ready to present to
OpenPOWER.  he cannot afford the time to be distracted.  i had to stop
myself from asking him to do something else, even 30 minutes ago.

the critical priority need right now is *coding* in order to meet the
deadline.

can we please, everyone, focus on coding and on completing the tasks as
fast as possible.

l.



-- 
---
crowd-funded eco-conscious hardware: https://www.crowdsupply.com/eoma68
_______________________________________________
libre-riscv-dev mailing list
libre-riscv-dev@lists.libre-riscv.org
http://lists.libre-riscv.org/mailman/listinfo/libre-riscv-dev

Re: [libre-riscv-dev] Merging Repositories and Auto-Generating Static Documentation

[Luke Kenneth Casson Leighton]

so is that clear, yehowshua, the detrimental implications to the
project if this decision were to go ahead?

i have been doing project time-management for a long time, always
thinking through the consequences of a decision, estimating completion
time fairly accurately, and we simply do not have the time to spare
(not even, really, to discuss it).  even Jean-Paul would be impacted
on the coriolis2 ASIC layout side because the changes result in him
having to change the way he supports us: his automated build scripts
would need updating to reflect changes to the repository structures.

with only 15 weeks left, we need people to knuckle down and get on
with the tasks, and regularly keep in touch about progress.  we don't
need extraneous non-essential tasks to be added to the list.

every extraneous non-essential task means that the functionality of
the ASIC has to be cut back even further from what has already been
removed.

does that help explain the consequences of what seems like an
otherwise simple and reasonable discussion?

l.

_______________________________________________
libre-riscv-dev mailing list
libre-riscv-dev@lists.libre-riscv.org
http://lists.libre-riscv.org/mailman/listinfo/libre-riscv-dev

Re: [libre-riscv-dev] Merging Repositories and Auto-Generating Static Documentation

[Yehowshua]

> so is that clear, yehowshua, the detrimental implications to the
> project if this decision were to go ahead?

Given we only have 4 people working on the bulk at the moment - the need to accelerate without impediment is clear. We can always circle back to this later.

For now, I have raised a bug report for the documentation.

https://bugs.libre-soc.org/show_bug.cgi?id=300

Yehowshua
_______________________________________________
libre-riscv-dev mailing list
libre-riscv-dev@lists.libre-riscv.org
http://lists.libre-riscv.org/mailman/listinfo/libre-riscv-dev

Re: [libre-riscv-dev] Merging Repositories and Auto-Generating Static Documentation

[Luke Kenneth Casson Leighton]

On Mon, May 4, 2020 at 2:10 PM Yehowshua <yimmanuel3@gatech.edu> wrote:
>
> > so is that clear, yehowshua, the detrimental implications to the
> > project if this decision were to go ahead?
>
> Given we only have 4 people working on the bulk at the moment - the need to accelerate without impediment is clear. We can always circle back to this later.
>
> For now, I have raised a bug report for the documentation.

appreciated.  i've closed it to indicate the seriousness of the need
to focus and get the tasks done as the absolute critical top priority.

l.

_______________________________________________
libre-riscv-dev mailing list
libre-riscv-dev@lists.libre-riscv.org
http://lists.libre-riscv.org/mailman/listinfo/libre-riscv-dev