mariotoffia / goasciidoc Goto Github PK

When generating a source with

// Time defines a _Unix Timestamp_ encoded as epoch seconds in JSON
//
// It is also able to create _time.Time_ with a specific timezone from
// this _UTC_ timestamp that have https://www.iana.org/time-zones[IANA compatible zone names].
// In order to create such _time.Time_ use the extension function
// @WithTimeZone.
type Time time.Time

the internal_parser prints the ast (meaning not supported):

0  *ast.SelectorExpr {
     1  .  X: *ast.Ident {
     2  .  .  NamePos: /home/martoffi/progs/crossbreed/platform/go-core/model/jsontime.go:17:11
     3  .  .  Name: "time"
     4  .  }
     5  .  Sel: *ast.Ident {
     6  .  .  NamePos: /home/martoffi/progs/crossbreed/platform/go-core/model/jsontime.go:17:16
     7  .  .  Name: "Time"
     8  .  }
     9  }

Line 17 is: type Time time.Time.

Initial thought is - around the figures of...

Hi.
I'm getting an error with Arrays:

type Color string
type Label struct {
	Name        string
	Description string
	color       Color
}
type LabelSet []Label

log:

not-implemented typeSpec.Type.(type) = *ast.ArrayType, ast-dump:
----------------------
     0  *ast.ArrayType {
     1  .  Lbrack: domain/labelset.go:5:15
     2  .  Elt: *ast.Ident {
     3  .  .  NamePos: domain/labelset.go:5:17
     4  .  .  Name: "Label"
     5  .  }
     6  }
----------------------

I'm using latest version v0.4.5

The originating error seems to come from here:

Would be cool to have this also implemented 😄

The listing of constants is not properly documented

const (
	AuthorizeRemoteTxRequests string = "AuthorizeRemoteTxRequests"
	ClockAlignedDataInterval  string = "ClockAlignedDataInterval"
	ConnectionTimeOut         string = "ConnectionTimeOut"
	ConnectorPhaseRotation    string = "ConnectorPhaseRotation"
	GetConfigurationMaxKeys   string = "GetConfigurationMaxKeys"
	HeartbeatInterval         string = "HeartbeatInterval"
	LocalAuthorizeOffline     string = "LocalAuthorizeOffline"
	LocalPreAuthorize         string = "LocalPreAuthorize"
)

Adding a comment to the const group leads to multiple calls

// This is not Working
const (
	AuthorizeRemoteTxRequests string = "AuthorizeRemoteTxRequests"
	ClockAlignedDataInterval  string = "ClockAlignedDataInterval"
	ConnectionTimeOut         string = "ConnectionTimeOut"
	ConnectorPhaseRotation    string = "ConnectorPhaseRotation"
	GetConfigurationMaxKeys   string = "GetConfigurationMaxKeys"
	HeartbeatInterval         string = "HeartbeatInterval"
	LocalAuthorizeOffline     string = "LocalAuthorizeOffline"
	LocalPreAuthorize         string = "LocalPreAuthorize"
)

Hi!
First of all this is an awesome project!

I noticed that in var blocks like

var(
  ...
)

the variables are duplicated.

Currently a Function that is bound to a certain struct is not rendered correctly since it is rendered as a standard function. It needs to be grouped under that particular struct.

Currently, each template override has to be explicitly configured with --overrides name=file, e.g.

go run github.com/mariotoffia/goasciidoc -o godoc.adoc -r import=docs/godoc-templates/import.tpl -r var=docs/godoc-templates/var.tpl

But it would be helpful if we can specify a template directory, and use the file basename as the name for *.tpl files, e.g.

$ ls docs/godoc-templates 
import.tpl  var.tpl

A file named var.tpl would provide a name for the var template (compare with var=... above)

go run github.com/mariotoffia/goasciidoc -o godoc.adoc --template-dir docs/godoc-templates

at the moment, I have to construct each individual argument like this:

$ for file in $(find docs/godoc-templates/*.tpl); do name="$(basename ${file%.*})" && printf "%s %s=%s" '-r' $name $file; done && printf '\n'
-r import=docs/godoc-templates/import.tpl -r var=docs/godoc-templates/var.tpl

which works, but isn't exactly pretty

When parsing gopackage.go the go/types - types.Config will segfault!

        conf := types.Config{Importer: importer.For("source", nil)}

	info := &types.Info{
		Types: make(map[ast.Expr]types.TypeAndValue),
		Defs:  make(map[*ast.Ident]types.Object),
		Uses:  make(map[*ast.Ident]types.Object),
	}

	if _, err := conf.Check(file.Name.Name, fset, files, info); err != nil {
		return nil, err
	}

The conf := types.Config(...) and if, _, err := conf.Check(...) are commented out due to this segfault.

Asciidoc is a great markup language. At the same time, Hugo is also a very good static website generation tool. I like Asciidoc and Hugo. Therefore, I am very much looking forward to an implementation in Go language.

I searched for relevant information and found at least three implementations:

1. bytesparadise/libasciidoc: A Golang library for processing Asciidoc files.
2. mariotoffia/goasciidoc: Document your go code using asciidoc instead of godoc
3. shuLhan/asciidoctor-go: [mirror] Native Go module for parsing and converting asciidoc markup language.

Asciidoc is now being standardized by the Eclipse Foundation: AsciiDoc Working Group | The Eclipse Foundation. Perhaps, you can work together to submit a more standards-compliant implementation to this working group.

Thanks again and good luck.

E.g. use @MethodName to include a certain method in a
[source,go]
....
Copy full method definition
....

It should also be templated in order to allow for overrides

When a plain function

func NewReportBuilder(
	json string,
	produce func(json string),
	rewritePath func(path string) string,
) *ReportBuilder {

	if nil == rewritePath {
		rewritePath = func(path string) string { return path }
	}

	return &ReportBuilder{
		json:        json,
		produce:     produce,
		rewritePath: rewritePath,
	}
}

is rendered. It will be rendered using ----- instead of ..... The above is rendered as:

== Functions

=== NewReportBuilder
[source, go]
----
func NewReportBuilder(
    json string,
    produce func(json string),
    rewritePath func(path string) string,
) *ReportBuilder
----

NewReportBuilder creates a new `ReportBuilder` with the provided _json_ as parameter.

If the _produce_ f...

Since struct, interfaces etc. do not emit \t instead only spaces are used.

for example:

type Producer struct {
        parseconfig goparser.ParseConfig
        paths []string
        outfile string
        index bool
        indexconfig string
        overrides map[string]string
        writer io.Writer
}

This needs to be adressed on type struct, interface, const etc but not on other places.

Since, those are only used when included and should not be added to the asciidoc document. This results that all tags are rendered.

Add a pre-processing step to clense tag::tag-name[] from the data

Allow for rendering a sample JSON document based on go structs. In addition interpret json tag.

type DsBuildingMeta struct {
	TimeZone DsMetaTimeStamp `json:"tz,omitempty"`
	Sensors map[string]DsMetaTimeStamp `json:"sensors,omitempty"`
}

E.g. this setup will not extract the fields and documentation:

type Baah struct {
  Foo struct {
    // Baz is a property
    Baz string
  }

The Decl for Baah is now

Foo struct {
  // Baz is a property
  Baz string
}

and that is not correct. It SHOULD be

Baah.Foo.Baz
Fax is a property

and the Foo Struct should be

type Baah struct {
  Foo struct {
   Baz string
  }

This requires more job when parsing the structs...