suggestion to not use docs/ conflicts with github-pages convention

[Sh1d0w]

Hi I have published several Flutter plugins.

Until today everything was working ok. I had to publish a change on one of my packages.

Upon running flutter packages pub publish I got the following error

I had this folder before, and it was not giving me such warnings.

Furthermore this warning conflicts with GitHub and does not makes sense at all. I have enabled Github pages integration for my repo, where I host the docs for the plugin. Github expects your Github pages source to be in the docs folder, but flutter complains I have to rename it to doc ...

Why this warning was introduced, is there any good reason for it and what can be done about it?

[Sh1d0w]

@zoechi Any official statement on this issue? It is very annoying to rename docs to doc back and forth after each package release.

The docs folder does not contain any files, that are related to dart documentation, they are just there for the Github Pages integration and are written in Markdown. IMO this should not trigger any warning.

[zoechi]

@jonasfj perhaps

[jonasfj]

Sorry, for the late reply..

It is very annoying to rename docs to doc back and forth after each package release.

You don't need to rename the folder... a suggestion is just that, a suggestion -- it can be ignored.

I'm not exactly sure if we should remove suggestion.. The convention it suggests to follow is well-established: https://www.dartlang.org/tools/pub/package-layout

On the other hand I definitely understand the desired to publish github pages from the master branch :)

---

@jcollins-g, does dartdoc read the contents of doc/ by default? Or is there some other reason we want to discourage use of a docs/ folder?

---

Note. I think we should find a resolution to this, but this suggestion shouldn't stop you from publishing packages and having github pages in docs/. But there are many ways we could attempt to solve this, we could have a .pubignore file, or add a list of ignore patterns in pubspec.yaml, or we could stop warning about docs/ specifically.

[Sh1d0w]

@jonasfj Thanks for your replay. Yep I can ignore the warning but then it would affect the package overall score in pub registry, no?

[jonasfj]

I can ignore the warning but then it would affect the package overall score in pub registry, no?

I'm not sure, maybe...but pana has a different set of checks, so it might not.

You are right, it's probably best to not include the docs/ folder in the package. It's a lot of files for people to download, and they are never going to be using those files...

[PiotrFLEURY]

Hi everyone

Any update on this issue ?

I'm trying to configure publication using Github actions and this warning make the job fail.

Is my only solution to force the publication ? It can be dangerous in my opinion.

A .pubignore or pub_options.yaml could be great to specify custom rules like the actual docs directory is not related to dart doc but to the Github pages.

# pub_options.yaml
rules:
  ignore_docs_folder: true

[sigurdm]

We actually now have support for .pubignore files.

Try making a .pubignore at the root containing:

/docs/

Should exclude the docs folder from being part of the publication and validation process.

[PiotrFLEURY]

It worked. Thank you @sigurdm 😀

I did not see the mention about pubignore file in the documentation

[sigurdm]

It is documented (though not in great detail) at https://dart.dev/tools/pub/publishing#what-files-are-published .

@jonasfj shared a bit more guidance in this stack overflow answer: https://stackoverflow.com/a/69767697 .

[sigurdm]

I will close this - not sure we want to do more here for now.