<div dir="ltr"><div>I see now that my reply to Nick on this wasn't reply-all. My bad!</div><div><br></div><div><span class="gmail-im"><font color="#a64d79">> Can Sphinx accept some extra text/context in the index page of the autogenerated library docs?</font></span></div><div>The answer to this is actually Yes.<span class="gmail-im"><font color="#a64d79"><br></font></span></div><br>This is the file that configures that page:<br><div><a href="https://github.com/datactive/bigbang/blob/main/docs/api-docs.rst">https://github.com/datactive/bigbang/blob/main/docs/api-docs.rst</a></div><div><br></div><div>Glad to see issue #502</div><div><br></div><div>I'm wondering if we should take the opportunity to think about the submodule structure of the code and come to some consensus around it.</div><div></div><div><div>Christoph has introduced some new submodule structure to the code,
which is all quite welcome, but now we have some inconsistencies that it
would be good to work out before committing to in our documentation.</div><div><br></div><div>A couple issues connected with this:</div><div><br></div><div><a href="https://github.com/datactive/bigbang/issues/435" target="_blank">https://github.com/datactive/bigbang/issues/435</a></div><div><a href="https://github.com/datactive/bigbang/issues/498" target="_blank">https://github.com/datactive/bigbang/issues/498</a></div><div><a href="https://github.com/datactive/bigbang/issues/414" target="_blank">https://github.com/datactive/bigbang/issues/414</a></div><div><br></div><div>We now have 'analysis' and 'visualization' submodules.</div><div>Maybe we should have an 'ingress' submodule and put the various mailing list scrapers in there?</div><font color="#888888"><div><br><br></div></font></div></div><br><div class="gmail_quote"><div dir="ltr" class="gmail_attr">On Mon, Nov 22, 2021 at 2:59 PM Christoph Becker <<a href="mailto:chrbecker01@gmail.com">chrbecker01@gmail.com</a>> wrote:<br></div><blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left:1px solid rgb(204,204,204);padding-left:1ex"><div dir="ltr"><div dir="ltr"><div><font color="#a64d79">> I have noticed that documentation on development (running tests, code of conduct, formatting, etc.) isn't included in the Readthedocs pages yet. Is that something we want to move over? Or do we think of the readme as primarily for bigbang developers and readthedocs as primarily for bigbang users?</font></div><div>Yes, the documentation on development should be part of the Readthedocs too, but we simply haven't had the time yet to polish and include it.</div><div><br></div><div><font color="#a64d79">> The API documentation is organized by file/library, which makes sense, but I'm not sure how easy that is for people to understand. Should we have an overview of how the code is organized so that someone new to the project knows what to look for where? E.g. mailing list crawling is done within these 4 files, archives and analysis is in these, these files were experimental and aren't regularly used, etc.</font></div><div>Yes, that sounds good to me :) Could you create a PR for that?</div><div><br></div><div><font color="#a64d79">> Can Sphinx accept some extra text/context in the index page of the autogenerated library docs?</font></div><div>I don't think so, but might be wrong.</div><div><br></div><div>BW,</div><div>Chris</div><div><br></div></div><br><div class="gmail_quote"><div dir="ltr" class="gmail_attr">Op vr 19 nov. 2021 om 14:24 schreef Nick Doty <<a href="mailto:npdoty@ischool.berkeley.edu" target="_blank">npdoty@ischool.berkeley.edu</a>>:<br></div><blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left:1px solid rgb(204,204,204);padding-left:1ex"><div dir="ltr"><div>Thanks Seb for getting this going! It's so nice to read documentation in this format, rather than spread haphazardly around readme and wiki pages.</div><br><div class="gmail_quote"><div dir="ltr" class="gmail_attr">On Fri, Oct 8, 2021 at 4:11 PM Sebastian Benthall <<a href="mailto:sbenthall@gmail.com" target="_blank">sbenthall@gmail.com</a>> wrote:<br></div><blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left:1px solid rgb(204,204,204);padding-left:1ex"><div dir="ltr">Hello,<br><div><br></div><div>New documentation us up on RTD, including autodocs for the code docstrings and the README, imported.</div><div><br></div><div><a href="https://bigbang-py.readthedocs.io/en/latest/" target="_blank">https://bigbang-py.readthedocs.io/en/latest/</a><br></div><div><br></div><div>Now that we have a location to put more expansive/complete documentation, we can have dedicated pages for issues, such as the <a href="https://github.com/datactive/bigbang/issues/414" target="_blank">data ingress/egress</a> we support.</div><div><br></div><div>Currently, all of our documentation is in the README, which has gotten quite long.</div><div><br></div><div>We have some options:</div><div> - (a) move material out of the README into dedicated pages that are rendered to the docs, keeping the README light, with "must have" information and links to the docs for other topics.</div><div> - (b) maintain information redundantly in the README and in Sphinx</div><div> - (c) Status quo: keep using the README for almost everything except autodocs.</div><div><br></div><div>My preference is for option (a).</div><div><br></div><div>I wonder how you all feel about the best way to organize the docs.</div></div></blockquote><div><br></div><div>I'm fine with option (a). I have noticed that documentation on development (running tests, code of conduct, formatting, etc.) isn't included in the Readthedocs pages yet. Is that something we want to move over? Or do we think of the readme as primarily for bigbang developers and readthedocs as primarily for bigbang users?</div><div><br></div><div>The API documentation is organized by file/library, which makes sense, but I'm not sure how easy that is for people to understand. Should we have an overview of how the code is organized so that someone new to the project knows what to look for where? E.g. mailing list crawling is done within these 4 files, archives and analysis is in these, these files were experimental and aren't regularly used, etc. Can Sphinx accept some extra text/context in the index page of the autogenerated library docs?</div><div><br></div><div>—npd</div></div></div>
_______________________________________________<br>
Bigbang-dev mailing list<br>
<a href="mailto:Bigbang-dev@data-activism.net" target="_blank">Bigbang-dev@data-activism.net</a><br>
<a href="https://lists.ghserv.net/mailman/listinfo/bigbang-dev" rel="noreferrer" target="_blank">https://lists.ghserv.net/mailman/listinfo/bigbang-dev</a><br>
</blockquote></div></div>
_______________________________________________<br>
Bigbang-dev mailing list<br>
<a href="mailto:Bigbang-dev@data-activism.net" target="_blank">Bigbang-dev@data-activism.net</a><br>
<a href="https://lists.ghserv.net/mailman/listinfo/bigbang-dev" rel="noreferrer" target="_blank">https://lists.ghserv.net/mailman/listinfo/bigbang-dev</a><br>
</blockquote></div>