Refactoring docs to be more easily navigable. (#219)

* updated doc.go.

* refactored docs to render doc strings.

* moved poly.go sequence structs to io subpackage.

* moved codon tests to dedicated directory.

checks/checks.go

@@ -1,8 +1,12 @@
+/*
+Package checks provides utilities to check for certain properties of a sequence.
+*/
 package checks
 
 import (
-	"github.com/TimothyStiles/poly/transform"
 	"strings"
+
+	"github.com/TimothyStiles/poly/transform"
 )
 
 // IsPalindromic accepts a sequence of even length and returns if it is

checks/checks_test.go

@@ -1,21 +1,25 @@
-package checks
+package checks_test
 
-import "testing"
+import (
+	"testing"
+
+	"github.com/TimothyStiles/poly/checks"
+)
 
 // This also needs an example test.
 func TestIsPalindromic(t *testing.T) {
-	ecori := IsPalindromic("GAATTC")
+	ecori := checks.IsPalindromic("GAATTC")
 	if ecori != true {
 		t.Errorf("IsPalindromic failed to call EcoRI a palindrome")
 	}
-	bsai := IsPalindromic("GGTCTC")
+	bsai := checks.IsPalindromic("GGTCTC")
 	if bsai != false {
 		t.Errorf("IsPalindromic failed call BsaI NOT a palindrome")
 	}
 }
 
 func TestGcContent(t *testing.T) {
-	content := GcContent("GGTATC")
+	content := checks.GcContent("GGTATC")
 	if content != 0.5 {
 		t.Errorf("GcContent did not properly calculate GC content")
 	}

clone/clone.go

@@ -1,21 +1,5 @@
-package clone
-
-import (
-	"errors"
-	"regexp"
-	"sort"
-	"strings"
-	"sync"
-
-	"github.com/TimothyStiles/poly/checks"
-	"github.com/TimothyStiles/poly/seqhash"
-	"github.com/TimothyStiles/poly/transform"
-)
-
-/******************************************************************************
-Apr 22, 2021
-
-Cloning stuff starts here.
+/*
+Package clone provides functions for cloning DNA sequences.
 
 Since 1973, the most common way to make recombinant DNA has been restriction
 enzyme cloning (though lately, homologous recombination based methods like
@@ -54,8 +38,20 @@ Keoni
 
 PS: We do NOT (yet) handle restriction enzymes which recognize one site but cut
 in multiple places (Type IIG enzymes) such as BcgI.
+*/
+package clone
 
-******************************************************************************/
+import (
+	"errors"
+	"regexp"
+	"sort"
+	"strings"
+	"sync"
+
+	"github.com/TimothyStiles/poly/checks"
+	"github.com/TimothyStiles/poly/seqhash"
+	"github.com/TimothyStiles/poly/transform"
+)
 
 // Part is a simple struct that can carry a circular or linear DNA sequence.
 // In the field of synthetic biology, the term "DNA Part" was popularized by

cmd/poly/commands.go

@@ -11,9 +11,9 @@ import (
 	"path/filepath"
 	"sync"
 
-	"github.com/TimothyStiles/poly"
 	"github.com/TimothyStiles/poly/io/genbank"
 	"github.com/TimothyStiles/poly/io/gff"
+	"github.com/TimothyStiles/poly/io/poly"
 	"github.com/TimothyStiles/poly/io/polyjson"
 	"github.com/TimothyStiles/poly/seqhash"
 	"github.com/urfave/cli/v2"

cmd/poly/commands_test.go

@@ -7,8 +7,8 @@ import (
 	"path/filepath"
 	"testing"
 
-	"github.com/TimothyStiles/poly"
 	"github.com/TimothyStiles/poly/io/genbank"
+	"github.com/TimothyStiles/poly/io/poly"
 	"github.com/TimothyStiles/poly/io/polyjson"
 	"github.com/google/go-cmp/cmp"
 	"github.com/google/go-cmp/cmp/cmpopts"

cmd/poly/doc.go

@@ -1,6 +1,6 @@
 /*
 
-Poly command line utility installation instructions:
+Poly command line utility installation instructions.
 
 Mac OSX
 
@@ -13,6 +13,6 @@ Windows
 	Coming soon...
 
 
-Usage: please make good use of our `-h` help flag. Everything is up to date there and well tested. 
+Usage: please make good use of our `-h` help flag. Everything is up to date there and well tested.
 */
 package main

doc.go

@@ -1,30 +1,34 @@
-/*Package poly is a go package for engineering organisms.
+/*
+Package poly is a Go package for engineering organisms.
 
+Synthetic biology has a software problem. I.E almost all
+of our field's software is slow, hard to maintain,
+and even harder to deploy.
 
+Poly solves that problem by providing a highly tested
+suite of common functions for engineering organisms
+through a simple interface in Go.
 
-Poly can be used in two ways.
+The reason why Go was choosen is that it's a highly popular
+language with a simple sytax and a large ecosystem of packages
+that makes it *extremely* easy to learn, use, and deploy.
+It's also on average 25X faster and more energy efficient that
+Python.
 
-	 1. As a Go library where you have finer control and can make magical things happen.
-	 2. As a command line utility where you can bash script your way to greatness and make DNA go brrrrrrrr.
+Eventually we intend for poly to provide all the functionality
+needed such that users can use it to engineer proteins which
+they can then optimize and insert into their organisms of choice.
 
+We've made great progress and are always looking for more support!
 
-Installation
+tl;dr
 
+Poly is awesome.
 
-These instructions assume that you already have a working go environment. If not see:
-	https://golang.org/doc/install
+Throw money at Tim's github sponsors page:
+https://github.com/sponsors/TimothyStiles
 
-
-Building Poly CLI and package from scratch:
-
-	git clone https://github.com/TimothyStiles/poly.git && cd poly && go build ./... && go install ./...
-
-
-
-Installing latest release of poly as a go package:
-	go get github.com/TimothyStiles/poly
-
-
-For CLI only instructions please checkout: https://pkg.go.dev/github.com/TimothyStiles/poly/poly
+Browse our subpackages to find the functionality and documentation you need:
+https://pkg.go.dev/github.com/TimothyStiles/poly#section-directories
 */
 package poly

io/example_test.go

@@ -1,4 +1,4 @@
-package io
+package io_test
 
 import (
 	"github.com/TimothyStiles/poly/io/fasta"
@@ -19,7 +19,8 @@ func Example() {
 	fastaInput := fasta.Read("fasta/data/base.fasta")
 	jsonInput := polyjson.Read("../data/puc19static.json")
 
-	// Poly can also output these file formats though I wouldn't try doing gbk<->gff or anything like that unless it's JSON.
+	// Poly can also output these file formats though I wouldn't try doing gbk<->gff
+	// or anything like that but JSON <-> anything and back should work.that unless it's JSON.
 
 	gff.Write(gffInput, "test.gff")
 	genbank.Write(gbkInput, "test.gbk")

io/genbank/genbank.go

@@ -17,12 +17,13 @@ import (
 	"io"
 	"io/ioutil"
 	"log"
-	"lukechampine.com/blake3"
 	"regexp"
 	"strconv"
 	"strings"
 
-	"github.com/TimothyStiles/poly"
+	"lukechampine.com/blake3"
+
+	"github.com/TimothyStiles/poly/io/poly"
 	"github.com/mitchellh/go-wordwrap"
 )
 

io/genbank/genbank_test.go

@@ -8,7 +8,7 @@ import (
 	"strings"
 	"testing"
 
-	"github.com/TimothyStiles/poly"
+	"github.com/TimothyStiles/poly/io/poly"
 	"github.com/google/go-cmp/cmp"
 	"github.com/google/go-cmp/cmp/cmpopts"
 )

io/gff/gff.go

@@ -15,13 +15,14 @@ import (
 	"bytes"
 	"io/ioutil"
 	"log"
-	"lukechampine.com/blake3"
 	"regexp"
 	"sort"
 	"strconv"
 	"strings"
 
-	"github.com/TimothyStiles/poly"
+	"lukechampine.com/blake3"
+
+	"github.com/TimothyStiles/poly/io/poly"
 )
 
 // Parse Takes in a string representing a gffv3 file and parses it into an Sequence object.

io/gff/gff_test.go

@@ -7,7 +7,7 @@ import (
 	"path/filepath"
 	"testing"
 
-	"github.com/TimothyStiles/poly"
+	"github.com/TimothyStiles/poly/io/poly"
 	"github.com/google/go-cmp/cmp"
 	"github.com/google/go-cmp/cmp/cmpopts"
 	"github.com/pmezard/go-difflib/difflib"

io/io_test.go

@@ -1,10 +1,10 @@
-package io_test
+package io
 
 import (
 	"testing"
 
-	"github.com/TimothyStiles/poly"
 	"github.com/TimothyStiles/poly/io/genbank"
+	"github.com/TimothyStiles/poly/io/poly"
 	"github.com/TimothyStiles/poly/io/polyjson"
 	"github.com/google/go-cmp/cmp"
 	"github.com/google/go-cmp/cmp/cmpopts"

poly.go → io/poly/poly.go

@@ -1,3 +1,17 @@
+/*
+Package poly provides the core Sequence struct and methods for working with DNA, RNA, and Amino Acid sequences in Poly.
+
+Each Sequence struct can be broken down into the following:
+
+Meta: Author, Date, Description, Name, Version, etc.
+Features:	A list of Feature structs containing feature locations and other information.
+Sequece:	The actual sequence string.
+
+As well as other info like source file checksums, etc.
+
+This package will likely be overhauled before 1.0 release to be more flexible and robust.
+So be on the lookup for breaking changes in future releases.
+*/
 package poly
 
 import (

io/polyjson/polyjson.go

@@ -1,10 +1,16 @@
+/*
+Package polyjson provides utilities to read and write poly.Sequence structs as JSON.
+
+Poly's JSON schema is still in flux so be on the lookout for breaking changes as we
+approach the 1.0 release.
+*/
 package polyjson
 
 import (
 	"encoding/json"
 	"io/ioutil"
 
-	"github.com/TimothyStiles/poly"
+	"github.com/TimothyStiles/poly/io/poly"
 )
 
 /******************************************************************************

io/polyjson/polyjson_test.go

@@ -1,4 +1,4 @@
-package polyjson
+package polyjson_test
 
 import (
 	"fmt"
@@ -7,9 +7,10 @@ import (
 	"path/filepath"
 	"testing"
 
-	"github.com/TimothyStiles/poly"
 	"github.com/TimothyStiles/poly/io/genbank"
 	"github.com/TimothyStiles/poly/io/gff"
+	"github.com/TimothyStiles/poly/io/poly"
+	"github.com/TimothyStiles/poly/io/polyjson"
 
 	"github.com/google/go-cmp/cmp"
 	"github.com/google/go-cmp/cmp/cmpopts"
@@ -22,15 +23,15 @@ JSON related tests begin here.
 ******************************************************************************/
 
 func ExampleRead() {
-	sequence := Read("../../data/sample.json")
+	sequence := polyjson.Read("../../data/sample.json")
 
 	fmt.Println(sequence.Meta.Source)
 	//output: Saccharomyces cerevisiae (baker's yeast)
 }
 
 func ExampleParse() {
 	file, _ := ioutil.ReadFile("../../data/sample.json")
-	sequence := Parse(file)
+	sequence := polyjson.Parse(file)
 
 	fmt.Println(sequence.Meta.Source)
 	//output: Saccharomyces cerevisiae (baker's yeast)
@@ -43,12 +44,12 @@ func ExampleWrite() {
 	}
 	defer os.RemoveAll(tmpDataDir)
 
-	sequence := Read("../../data/sample.json")
+	sequence := polyjson.Read("../../data/sample.json")
 
 	tmpJSONFilePath := filepath.Join(tmpDataDir, "sample.json")
-	Write(sequence, tmpJSONFilePath)
+	polyjson.Write(sequence, tmpJSONFilePath)
 
-	testSequence := Read(tmpJSONFilePath)
+	testSequence := polyjson.Read(tmpJSONFilePath)
 
 	fmt.Println(testSequence.Meta.Source)
 	//output: Saccharomyces cerevisiae (baker's yeast)
@@ -64,9 +65,9 @@ func TestGbkToJSON(t *testing.T) {
 	testSequence := genbank.Read("../../data/puc19.gbk")
 
 	tmpJSONFilePath := filepath.Join(tmpDataDir, "puc19.json")
-	Write(testSequence, tmpJSONFilePath)
+	polyjson.Write(testSequence, tmpJSONFilePath)
 
-	readTestSequence := Read(tmpJSONFilePath)
+	readTestSequence := polyjson.Read(tmpJSONFilePath)
 
 	if diff := cmp.Diff(testSequence, readTestSequence, cmpopts.IgnoreFields(poly.Feature{}, "ParentSequence")); diff != "" {
 		t.Errorf(" mismatch (-want +got):\n%s", diff)
@@ -83,9 +84,9 @@ func TestGffToJSON(t *testing.T) {
 	gffTestSequence := gff.Read("../../data/ecoli-mg1655-short.gff")
 
 	tmpJSONFilePath := filepath.Join(tmpDataDir, "ecoli-mg1655-short.json")
-	Write(gffTestSequence, tmpJSONFilePath)
+	polyjson.Write(gffTestSequence, tmpJSONFilePath)
 
-	gffReadTestSequence := Read(tmpJSONFilePath)
+	gffReadTestSequence := polyjson.Read(tmpJSONFilePath)
 
 	if diff := cmp.Diff(gffTestSequence, gffReadTestSequence, cmpopts.IgnoreFields(poly.Feature{}, "ParentSequence")); diff != "" {
 		t.Errorf(" mismatch (-want +got):\n%s", diff)

primers/primers.go

@@ -1,3 +1,22 @@
+/*
+Package primers provides utilities for creating primers and DNA barcodes.
+
+Primers are short sequences of DNA that can be used to amplify DNA sequences
+and they are the workhorse of modern molecular biology.
+
+Essentially primers are short pieces of single stranded DNA that can
+bind to a target sequence of single stranded DNA. These primers serve as a
+marker for polymerases (the enzyme Poly is named after!) to bind and start adding
+free floating nucleotides (ACTGs) to a single strand piece of DNA to form a
+double stranded piece of DNA.
+
+This is a crucial step in the process of PCR (polymerase chain reaction).
+https://en.wikipedia.org/wiki/Polymerase_chain_reaction
+
+You can read more about that at the link above but just know that an absolute huge
+number of protocols from diagnostics to plasmid cloning use these primers so they're
+super important.
+*/
 package primers
 
 import (