Re: Updating the Cookbook (Resend)
Gary Murphy <[email protected]> Wed, 17 Jan 2024 07:49:24 -0600
| Newsgroups | gmane.comp.java.bio.general |
|---|---|
| Message-ID | <[email protected]> |
This is a multi-part message in MIME format. --===============3589421577439550124== Content-Type: multipart/alternative; boundary="------------3FvF9EvjDwLR83SA18WeANaN" Content-Language: en-US This is a multi-part message in MIME format. --------------3FvF9EvjDwLR83SA18WeANaN Content-Type: text/plain; charset=UTF-8; format=flowed Content-Transfer-Encoding: 8bit Okay. I will put efforts in that direction. That will be easier. On 1/16/24 13:01, Jose Duarte wrote: > Just want to confirm that the preferred way to write documentation for > BioJava is through the tutorial github site that Peter points out: > https://github.com/biojava/biojava-tutorial > > The docs and tutorials in github.io <http://github.io> are quite > outdated and came from migrating the previous wiki. It really needs a > good clean up. > > Jose > > > On Mon, 15 Jan 2024 at 08:39, Gary Murphy <[email protected]> wrote: > > Yes replying to you only was in error. I will take a look at the > Python > project you mentioned. I also got the Jekyll code going by > regressing > to a previous version. > > Thanks again for the feedback. > > > On 1/15/24 10:19, Peter Cock wrote: > > Whoops - I missed that as I initially assumed hilberglm was > > someone else. Sorry. By the way, I'm happy to take this thread > > back to the mailing list if replying to just me was in error. > > > > In Biopython we use a tool called blacken-docs to apply the same > > automated formatting style (defined in a tool called black) to the > > examples in our documentation that we use in the main code: > > > > https://pypi.org/project/blacken-docs/ > > > > I don't know if there is something similar possible in Java? > > > > As to the automated builds with Jekyll, there are likely some > > fixes made on https://github.com/biopython/biopython.github.io/ > > which can be copied over. > > > > Peter > > > > On Mon, Jan 15, 2024 at 4:06 PM Gary Murphy > <[email protected]> wrote: > >> Thank you for getting back to me so quickly. Yes, I am the > Gary Murphy > >> that forked the source to take a look at it and understand how > to build > >> it. I should have posted the official github URL instead of my > fork. > >> > >> I have some code that reads FASTA files using Java streams that I > >> haven't submitted a pull request for, but I wanted to have a > handle on > >> how to document it if it was accepted. Specifically, > >> _wiki/BioJava_CookBook_Core_FastaReadWrite.md is the one I updated > >> locally, but haven't pushed. I also noted a lot of formatting > errors on > >> the source code in the Cookbook, so I would be changing those > only when > >> I update a page... a global update would be pretty time-consuming. > >> > >> More generally, since I am learning the code base, I thought it > would be > >> beneficial for me to add documentation when I learn how to do > things in > >> the normal course of my job that I had to jump into the source code > >> and/or test cases to understand. > >> > >> The first thing I would be updating is how to update the > documentation. > >> The Jekyll docker container is broken out of the gate, so I had to > >> figure out how to get the build server running locally to ensure my > >> changes were getting rendered properly. > >> > >> I have spent some time in the tutorials. They are extremely > helpful and > >> seem to be more recently updated. > >> > >> > >> On 1/15/24 09:49, Peter Cock wrote: > >>> I'd guess the source you want is > https://github.com/biojava/biojava.github.io > >>> but Gary Murphy's version > https://github.com/hilbertglm/biojava.github.io.git > >>> looks to be the same right now - this is the main BioJava > website and > >>> it does indeed look not to have been updated recently. This > includes what > >>> used to be the wiki content (including the cookbook), now as > markdown pages. > >>> This repository also includes API documentation. > >>> > >>> What specifically did you want to change here? e.g. An example URL > >>> > >>> See also https://github.com/biojava/biojava-tutorial which has > been changed > >>> much more recently. > >>> > >>> Peter > >>> > >>> On Mon, Jan 15, 2024 at 2:53 PM Gary Murphy > <[email protected]> wrote: > >>>> Sorry if this is a duplicate, but the mailing list > confirmation got moved to the spam folder, so I don't know if this > original e-mail was honored. > >>>> > >>>> ----- > >>>> > >>>> I am new to the biojava community, so I thought I would be a > good candidate to update some of the documentation as I discover > how to accomplish my goals with biojava. > >>>> > >>>> I got the source for the Cookbook > (https://github.com/hilbertglm/biojava.github.io.git), and it > seems like it is a bit out of date with quite a few formatting > issues for the source code. > >>>> > >>>> Before I start... > >>>> > >>>> Is there any effort I should be aware of for a new one, or is > anyone actively working on it? If so, we should coordinate efforts > >>>> Does anyone have any issue with my removing the non-breaking > spaces in the source code. It shows as [NBSP] in Intellij, so it > is going to be tough to do any editing on that. > >>>> > >>>> Any thoughts would be appreciated. > >>>> > >>>> _______________________________________________ > >>>> Biojava-l mailing list - [email protected] > >>>> https://mailman.open-bio.org/mailman/listinfo/biojava-l > >>> _______________________________________________ > >>> Biojava-l mailing list - [email protected] > >>> https://mailman.open-bio.org/mailman/listinfo/biojava-l > _______________________________________________ > Biojava-l mailing list - [email protected] > https://mailman.open-bio.org/mailman/listinfo/biojava-l > --------------3FvF9EvjDwLR83SA18WeANaN Content-Type: text/html; charset=UTF-8 Content-Transfer-Encoding: 8bit <html> <head> <meta http-equiv="Content-Type" content="text/html; charset=UTF-8"> </head> <body> <p>Okay. I will put efforts in that direction. That will be easier.<br> </p> <div class="moz-cite-prefix">On 1/16/24 13:01, Jose Duarte wrote:<br> </div> <blockquote type="cite" cite="mid:CAHhO=JFJELdcz_HeMv7b+aCHWkcMJSyg46ffBgF2sa6Z5bgMZw@mail.gmail.com"> <meta http-equiv="content-type" content="text/html; charset=UTF-8"> <div dir="ltr">Just want to confirm that the preferred way to write documentation for BioJava is through the tutorial github site that Peter points out: <a href="https://github.com/biojava/biojava-tutorial" moz-do-not-send="true" class="moz-txt-link-freetext">https://github.com/biojava/biojava-tutorial</a> <div><br> </div> <div>The docs and tutorials in <a href="http://github.io" moz-do-not-send="true">github.io</a> are quite outdated and came from migrating the previous wiki. It really needs a good clean up. </div> <div><br> <div>Jose</div> </div> <div><br> </div> </div> <br> <div class="gmail_quote"> <div dir="ltr" class="gmail_attr">On Mon, 15 Jan 2024 at 08:39, Gary Murphy <<a href="mailto:[email protected]" moz-do-not-send="true" class="moz-txt-link-freetext">[email protected]</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">Yes replying to you only was in error. I will take a look at the Python <br> project you mentioned. I also got the Jekyll code going by regressing <br> to a previous version.<br> <br> Thanks again for the feedback.<br> <br> <br> On 1/15/24 10:19, Peter Cock wrote:<br> > Whoops - I missed that as I initially assumed hilberglm was<br> > someone else. Sorry. By the way, I'm happy to take this thread<br> > back to the mailing list if replying to just me was in error.<br> ><br> > In Biopython we use a tool called blacken-docs to apply the same<br> > automated formatting style (defined in a tool called black) to the<br> > examples in our documentation that we use in the main code:<br> ><br> > <a href="https://pypi.org/project/blacken-docs/" rel="noreferrer" target="_blank" moz-do-not-send="true" class="moz-txt-link-freetext">https://pypi.org/project/blacken-docs/</a><br> ><br> > I don't know if there is something similar possible in Java?<br> ><br> > As to the automated builds with Jekyll, there are likely some<br> > fixes made on <a href="https://github.com/biopython/biopython.github.io/" rel="noreferrer" target="_blank" moz-do-not-send="true" class="moz-txt-link-freetext">https://github.com/biopython/biopython.github.io/</a><br> > which can be copied over.<br> ><br> > Peter<br> ><br> > On Mon, Jan 15, 2024 at 4:06 PM Gary Murphy <<a href="mailto:[email protected]" target="_blank" moz-do-not-send="true" class="moz-txt-link-freetext">[email protected]</a>> wrote:<br> >> Thank you for getting back to me so quickly. Yes, I am the Gary Murphy<br> >> that forked the source to take a look at it and understand how to build<br> >> it. I should have posted the official github URL instead of my fork.<br> >><br> >> I have some code that reads FASTA files using Java streams that I<br> >> haven't submitted a pull request for, but I wanted to have a handle on<br> >> how to document it if it was accepted. Specifically,<br> >> _wiki/BioJava_CookBook_Core_FastaReadWrite.md is the one I updated<br> >> locally, but haven't pushed. I also noted a lot of formatting errors on<br> >> the source code in the Cookbook, so I would be changing those only when<br> >> I update a page... a global update would be pretty time-consuming.<br> >><br> >> More generally, since I am learning the code base, I thought it would be<br> >> beneficial for me to add documentation when I learn how to do things in<br> >> the normal course of my job that I had to jump into the source code<br> >> and/or test cases to understand.<br> >><br> >> The first thing I would be updating is how to update the documentation.<br> >> The Jekyll docker container is broken out of the gate, so I had to<br> >> figure out how to get the build server running locally to ensure my<br> >> changes were getting rendered properly.<br> >><br> >> I have spent some time in the tutorials. They are extremely helpful and<br> >> seem to be more recently updated.<br> >><br> >><br> >> On 1/15/24 09:49, Peter Cock wrote:<br> >>> I'd guess the source you want is <a href="https://github.com/biojava/biojava.github.io" rel="noreferrer" target="_blank" moz-do-not-send="true" class="moz-txt-link-freetext">https://github.com/biojava/biojava.github.io</a><br> >>> but Gary Murphy's version <a href="https://github.com/hilbertglm/biojava.github.io.git" rel="noreferrer" target="_blank" moz-do-not-send="true" class="moz-txt-link-freetext">https://github.com/hilbertglm/biojava.github.io.git</a><br> >>> looks to be the same right now - this is the main BioJava website and<br> >>> it does indeed look not to have been updated recently. This includes what<br> >>> used to be the wiki content (including the cookbook), now as markdown pages.<br> >>> This repository also includes API documentation.<br> >>><br> >>> What specifically did you want to change here? e.g. An example URL<br> >>><br> >>> See also <a href="https://github.com/biojava/biojava-tutorial" rel="noreferrer" target="_blank" moz-do-not-send="true" class="moz-txt-link-freetext">https://github.com/biojava/biojava-tutorial</a> which has been changed<br> >>> much more recently.<br> >>><br> >>> Peter<br> >>><br> >>> On Mon, Jan 15, 2024 at 2:53 PM Gary Murphy <<a href="mailto:[email protected]" target="_blank" moz-do-not-send="true" class="moz-txt-link-freetext">[email protected]</a>> wrote:<br> >>>> Sorry if this is a duplicate, but the mailing list confirmation got moved to the spam folder, so I don't know if this original e-mail was honored.<br> >>>><br> >>>> -----<br> >>>><br> >>>> I am new to the biojava community, so I thought I would be a good candidate to update some of the documentation as I discover how to accomplish my goals with biojava.<br> >>>><br> >>>> I got the source for the Cookbook (<a href="https://github.com/hilbertglm/biojava.github.io.git" rel="noreferrer" target="_blank" moz-do-not-send="true" class="moz-txt-link-freetext">https://github.com/hilbertglm/biojava.github.io.git</a>), and it seems like it is a bit out of date with quite a few formatting issues for the source code.<br> >>>><br> >>>> Before I start...<br> >>>><br> >>>> Is there any effort I should be aware of for a new one, or is anyone actively working on it? If so, we should coordinate efforts<br> >>>> Does anyone have any issue with my removing the non-breaking spaces in the source code. It shows as [NBSP] in Intellij, so it is going to be tough to do any editing on that.<br> >>>><br> >>>> Any thoughts would be appreciated.<br> >>>><br> >>>> _______________________________________________<br> >>>> Biojava-l mailing list - <a href="mailto:[email protected]" target="_blank" moz-do-not-send="true" class="moz-txt-link-freetext">[email protected]</a><br> >>>> <a href="https://mailman.open-bio.org/mailman/listinfo/biojava-l" rel="noreferrer" target="_blank" moz-do-not-send="true" class="moz-txt-link-freetext">https://mailman.open-bio.org/mailman/listinfo/biojava-l</a><br> >>> _______________________________________________<br> >>> Biojava-l mailing list - <a href="mailto:[email protected]" target="_blank" moz-do-not-send="true" class="moz-txt-link-freetext">[email protected]</a><br> >>> <a href="https://mailman.open-bio.org/mailman/listinfo/biojava-l" rel="noreferrer" target="_blank" moz-do-not-send="true" class="moz-txt-link-freetext">https://mailman.open-bio.org/mailman/listinfo/biojava-l</a><br> _______________________________________________<br> Biojava-l mailing list - <a href="mailto:[email protected]" target="_blank" moz-do-not-send="true" class="moz-txt-link-freetext">[email protected]</a><br> <a href="https://mailman.open-bio.org/mailman/listinfo/biojava-l" rel="noreferrer" target="_blank" moz-do-not-send="true" class="moz-txt-link-freetext">https://mailman.open-bio.org/mailman/listinfo/biojava-l</a><br> </blockquote> </div> </blockquote> </body> </html> --------------3FvF9EvjDwLR83SA18WeANaN-- --===============3589421577439550124== Content-Type: text/plain; charset="us-ascii" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit Content-Disposition: inline _______________________________________________ Biojava-l mailing list - [email protected] https://mailman.open-bio.org/mailman/listinfo/biojava-l --===============3589421577439550124==--