Re: Updating the Cookbook (Resend)
Jose Duarte <[email protected]> Tue, 16 Jan 2024 11:01:06 -0800
| Newsgroups | gmane.comp.java.bio.general |
|---|---|
| Message-ID | <CAHhO=JFJELdcz_HeMv7b+aCHWkcMJSyg46ffBgF2sa6Z5bgMZw@mail.gmail.com> |
--===============8873679505657194844== Content-Type: multipart/alternative; boundary="00000000000052cf98060f14c1f0" --00000000000052cf98060f14c1f0 Content-Type: text/plain; charset="UTF-8" Content-Transfer-Encoding: quoted-printable 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 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=E2=80=AFPM Gary Murphy <[email protected]= om> > wrote: > >> Thank you for getting back to me so quickly. Yes, I am the Gary Murph= y > >> that forked the source to take a look at it and understand how to buil= d > >> 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 o= n > >> the source code in the Cookbook, so I would be changing those only whe= n > >> 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 i= n > >> 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 an= d > >> 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=E2=80=AFPM Gary Murphy <hilbertglm@gmail= .com> > 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 > --00000000000052cf98060f14c1f0 Content-Type: text/html; charset="UTF-8" Content-Transfer-Encoding: quoted-printable <div dir=3D"ltr">Just want to confirm that the preferred way to write docum= entation for BioJava is through the tutorial github site that Peter points = out:=C2=A0<a href=3D"https://github.com/biojava/biojava-tutorial">https://g= ithub.com/biojava/biojava-tutorial</a><div><br></div><div>The docs and tuto= rials in <a href=3D"http://github.io">github.io</a> are quite outdated and = came from migrating the previous wiki. It really needs a good clean up.=C2= =A0</div><div><br><div>Jose</div></div><div><br></div></div><br><div class= =3D"gmail_quote"><div dir=3D"ltr" class=3D"gmail_attr">On Mon, 15 Jan 2024 = at 08:39, Gary Murphy <<a href=3D"mailto:[email protected]">hilbertgl= [email protected]</a>> wrote:<br></div><blockquote class=3D"gmail_quote" style= =3D"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.=C2=A0 I will take a look = at the Python <br> project you mentioned.=C2=A0 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=3D"https://pypi.org/project/blacken-docs/" rel=3D"noreferrer" = target=3D"_blank">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=3D"https://github.com/biopython/biopython.github= .io/" rel=3D"noreferrer" target=3D"_blank">https://github.com/biopython/bio= python.github.io/</a><br> > which can be copied over.<br> ><br> > Peter<br> ><br> > On Mon, Jan 15, 2024 at 4:06=E2=80=AFPM Gary Murphy <<a href=3D"mai= lto:[email protected]" target=3D"_blank">[email protected]</a>> wr= ote:<br> >> Thank you for getting back to me so quickly.=C2=A0 Yes, I am the G= ary Murphy<br> >> that forked the source to take a look at it and understand how to = build<br> >> it.=C2=A0 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 h= andle on<br> >> how to document it if it was accepted.=C2=A0 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 wo= uld be<br> >> beneficial for me to add documentation when I learn how to do thin= gs in<br> >> the normal course of my job that I had to jump into the source cod= e<br> >> and/or test cases to understand.<br> >><br> >> The first thing I would be updating is how to update the documenta= tion.<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 m= y<br> >> changes were getting rendered properly.<br> >><br> >> I have spent some time in the tutorials. They are extremely helpfu= l 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=3D"https://github= .com/biojava/biojava.github.io" rel=3D"noreferrer" target=3D"_blank">https:= //github.com/biojava/biojava.github.io</a><br> >>> but Gary Murphy's version <a href=3D"https://github.com/hi= lbertglm/biojava.github.io.git" rel=3D"noreferrer" target=3D"_blank">https:= //github.com/hilbertglm/biojava.github.io.git</a><br> >>> looks to be the same right now - this is the main BioJava webs= ite and<br> >>> it does indeed look not to have been updated recently. This in= cludes what<br> >>> used to be the wiki content (including the cookbook), now as m= arkdown 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=3D"https://github.com/biojava/biojava-tutoria= l" rel=3D"noreferrer" target=3D"_blank">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=E2=80=AFPM Gary Murphy <<a hre= f=3D"mailto:[email protected]" target=3D"_blank">[email protected]</a= >> wrote:<br> >>>> Sorry if this is a duplicate, but the mailing list confirm= ation 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=3D"https://gith= ub.com/hilbertglm/biojava.github.io.git" rel=3D"noreferrer" target=3D"_blan= k">https://github.com/hilbertglm/biojava.github.io.git</a>), and it seems l= ike it is a bit out of date with quite a few formatting issues for the sour= ce 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-breaki= ng spaces in the source code.=C2=A0 It shows as [NBSP] in Intellij, so it i= s going to be tough to do any editing on that.<br> >>>><br> >>>> Any thoughts would be appreciated.<br> >>>><br> >>>> _______________________________________________<br> >>>> Biojava-l mailing list=C2=A0 -=C2=A0 <a href=3D"mailto:Bio= [email protected]" target=3D"_blank">[email protected]</a><br> >>>> <a href=3D"https://mailman.open-bio.org/mailman/listinfo/b= iojava-l" rel=3D"noreferrer" target=3D"_blank">https://mailman.open-bio.org= /mailman/listinfo/biojava-l</a><br> >>> _______________________________________________<br> >>> Biojava-l mailing list=C2=A0 -=C2=A0 <a href=3D"mailto:Biojava= [email protected]" target=3D"_blank">[email protected]</a><br> >>> <a href=3D"https://mailman.open-bio.org/mailman/listinfo/bioja= va-l" rel=3D"noreferrer" target=3D"_blank">https://mailman.open-bio.org/mai= lman/listinfo/biojava-l</a><br> _______________________________________________<br> Biojava-l mailing list=C2=A0 -=C2=A0 <a href=3D"mailto:[email protected]= g" target=3D"_blank">[email protected]</a><br> <a href=3D"https://mailman.open-bio.org/mailman/listinfo/biojava-l" rel=3D"= noreferrer" target=3D"_blank">https://mailman.open-bio.org/mailman/listinfo= /biojava-l</a><br> </blockquote></div> --00000000000052cf98060f14c1f0-- --===============8873679505657194844== 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 --===============8873679505657194844==--