`docs` folder is not in `.gitignore`

[chessmadridista]

What is the issue?

The docs folder gets created when make run command is executed in the terminal. When I do git status, it shows docs folder as untracked.

It is not included in .gitignore.

Here is a screenshot of the same.

Proposed solution

The docs folder should be included in .gitignore.

[chessmadridista]

I will be happy to take up this issue.

Please let me know in case something is amiss in my understanding and there is a reason why it is not included in .gitignore.

[cwarnermm]

The make run command doesn't currently output files to the same directory as the make build command. This is a known issue of low priority that doesn't impact generated docs output. I'd prefer to address an issue like this by updating the makefile to ensure output is in the correct directories. Let me know if you're open to investigating the changes needed to the makefile.

[chessmadridista]

The make run command doesn't currently output files to the same directory as the make build command. This is a known issue of low priority that doesn't impact generated docs output. I'd prefer to address an issue like this by updating the makefile to ensure output is in the correct directories. Let me know if you're open to investigating the changes needed to the makefile.

I have a couple of questions:

1. ...ensure output is in the correct directories...

So should the docs folder be created inside the dist directory when make run is executed? Or in some other directory?

2. Do docs and dist folder serve different purposes?
3. What is the harm in adding docs folder to .gitignore if it is used only for development purposes?
4. What benefits do we get if we don't add docs folder to .gitignore?

New solution

In config.toml file, I just need to change the path in line #8: publishDir = "${new_path}" Here new_path is the placeholder. Once I know the exact path, I will replace it here.

[cwarnermm]

@chessmadridista - The docs and dist- related build commands serve different purposes and produce different outputs. The make run command (to /docs) results in a live preview of the docs site which is very useful for local development, whereas the make build command (to /dist) produces full static HTML output. Our build and production pipelines make use of the latter.

I've confirmed that the /docs directory isn't Git-version controlled, and that running make run on a clean clone of the repository results in 900+ files, representing the output in the /docs directory. I can appreciate what you're asking and why.

Including the docs directory in .gitignore is a reasonable initial step. Ideally, I'd prefer to address the known inconsistency of the make run command outputting to a different directory as the make build command within the makefile. However, the Mattermost Docs team doesn't have bandwidth to take on an investigation in this area at this time.

If you're open to creating the docs PR introducing the .gitignore update, I'm open to accepting it.

[chessmadridista]

Hi @cwarnermm, thank you for the detailed clarification!

Sure, I will create a PR having the docs folder in .gitignore.

Shall I create another issue for finding out the root cause of why the files are being made in docs folder instead of the dist folder when make run is executed?

[cwarnermm]

That would be really great, @chessmadridista! Thank you!

[chessmadridista]

That would be really great, @chessmadridista! Thank you!

Hi @cwarnermm, I am happy to be of help!

1383 has been created to investigate the Makefile issue related to docs and dist.