search

go101 / golds

An experimental Go local docs server/generator and code reader implemented with some fresh ideas.
https://go101.org/apps-and-libs/golds.html
MIT License
600 stars 29 forks source link

Generate single page #19

Open cristaloleg opened 3 years ago

cristaloleg commented 3 years ago

Hi, thank for the golds it's amazing. I was looking for a param, where I can generate docs for few packages (with a common root, but probably it's not so important) but haven't found.

Is there a chance that this param can be added? Thanks!

zigo101 commented 3 years ago

@cristaloleg Could you elaborate more?

Is the idea the same as the ones described in https://github.com/go101/golds/issues/9 and https://github.com/go101/golds/issues/3?

zigo101 commented 3 years ago

ping @cristaloleg

cristaloleg commented 3 years ago

Woah, have missed your previous comment. So, my case was "I want to collect all the declarations in 1 HTML file".

Suppose I've a Go module with 3 packages foo, bar and bar/baz. In the end I would like to have doc.html with foo, bar and bar/baz documentation (funcs, types, consts, etc).

I don't think it's the same as #3 or #9

zigo101 commented 3 years ago

Is it supposed for one module or for all parsed packages?

The page might be very long. So if it is created, it might be best to list the items as an index table.

cristaloleg commented 3 years ago

Yep, well, there was a filter to skip mocks or few codegen packages.

Agree, it can be long, but you've 1 doc which is super easy to grep and host (not the best cast but was good solution for one of our projects and non-tech team).

zigo101 commented 3 years ago

So it is a page merged all package pages. The page shouldn't include std packages, right? And how about other 3rd-party dependency packages? Is it ok to link their items to pkg.go.dev?

And how to handle source code pages? To avoid generating source code pages, is it acceptable to link source code to external websites?

If std and 3rd-party dependencies are excluded, using external source code, and disabling some other features (id-ref pages and method-implementation pages), it might be feasible for small Go modules.

cristaloleg commented 3 years ago

Exactly. No std packages (however this can be a good feature, but most cases will exclude stdlib). No deps or vendor, only private repos. What do you mean by linking items to pkg.go.dev?

Source code pages was linked to the local machine, so running doc generator will produce local working HTML page.

zigo101 commented 3 years ago

What do you mean by linking items to pkg.go.dev?

In package doc pages, there are many links to other packages. It might be not a good idea to disable these links,

And currently, Golds will generate a page for each source code file. And there are many links from package docs pages to source code pages.

As you only need one page, I think you might don't want the source code pages to be generated. So is it ok to change the links to external source code hosting websites?

zigo101 commented 3 years ago

As you only need one page, I think you might don't want the source code pages to be generated. So is it ok to change the links to external source code hosting websites?

Aha, it looks this is an overthinking. But should the source code pages of your private projects be generated? If not, then the links from you package doc page to these source code pages will be disabled.

cristaloleg commented 3 years ago

Probably should be, but this was out of scope for my original questions :)

zigo101 commented 3 years ago

OK, I will add this to the todo list now. But I think it might not be implemented soon.

The last question: how to determine your private packages? The packages in the current directory?

cristaloleg commented 3 years ago

Yep, exactly, packages in the current directory.