[Biojava-l] Updating the Cookbook (Resend)

[Jose Duarte]

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 <hilbertglm at gmail.com> 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 <hilbertglm at gmail.com>
> 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 <hilbertglm at 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  -  Biojava-l at biojava.org
> >>>> https://mailman.open-bio.org/mailman/listinfo/biojava-l
> >>> _______________________________________________
> >>> Biojava-l mailing list  -  Biojava-l at biojava.org
> >>> https://mailman.open-bio.org/mailman/listinfo/biojava-l
> _______________________________________________
> Biojava-l mailing list  -  Biojava-l at biojava.org
> https://mailman.open-bio.org/mailman/listinfo/biojava-l
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://mailman.open-bio.org/pipermail/biojava-l/attachments/20240116/2f7908ff/attachment.htm>