[Chocorean]

Fixes #1187
Fixes #2224
Fixes #1156
Fixes #2246

Hopefully this is not just another duplicate and will act as a summary for the state of the "ignore" feature of mdbook.

This is a merge of #1908 onto main, with conflicts fixed.

As far as I have found, it would:

1. close:

• Use an optional .mdbookignore file to specify files to not copy to the output directory #1187
• Emacs lockfiles produce "Rendering failed" errors #2224
• Feature: suppress copying files by configuration #1156
• Prevent mdBook from recursively copying all files in src to dest #2246

2. supersede:

• Ignore files listed in .mdbookignore during build #1908 (the one we are merging here)
• feat: add 'no-copy-extra-files' flag to html renderer, preventing external files from being copied to the dest dir #2247
• Support for HTML Renderer to honor .gitignore #2991
• Ignore files listed in .mdbookignore during build #2183

EDIT:

This PR adds the support for a .mdbookignore file, found under src/, which acts as a ignore system to prevent the inclusion of specific files in the output directory.

I believe all the comments from #1908 were addressed

@rustbot ready

[Chocorean]

Shouldn't .mdbookignore be ignored by default? seems odd to me to include it

View changes since the review

[DanielEScherzer]

community review: some suggestions

View changes since this review

[Chocorean]

@DanielEScherzer Hello there, thanks for the review! I agree with you on all points. I reverted the unrelated changes and applied your suggestion

[GuillaumeGomez]

Some small nits but otherwise looks good to me. Thanks for the PR and thanks @DanielEScherzer for the review!

View changes since this review

[rustbot]

Reminder, once the PR becomes ready for a review, use @rustbot ready.

[Chocorean]

Comments addressed ! @rustbot ready

[GuillaumeGomez]

Time to squash all commits now. :)

[Chocorean]

@GuillaumeGomez I hope I got this right

[GuillaumeGomez]

Looks all good to me, thanks! Since it's a new feature, let's ping the rest of the team.

@rfcbot fcp merge mdbook

[rust-rfcbot]

@GuillaumeGomez has proposed to merge this. The next step is review by the rest of the tagged team members:

• @GuillaumeGomez
• @camelid
• @notriddle

Concerns:

• bespoke interface resolved by Add support for ignoring files when building the book #3229 (comment)

Once a majority of reviewers approve (and at most 2 approvals are outstanding), this will enter its final comment period. If you spot a major issue that hasn't been raised at any point in this process, please speak up!

See this document for info about what commands tagged team members can give me.

[notriddle]

Git, and systems like Git, allow you to put an ignore file in a subdirectory, allowing you to apply the rules to a particular scope. It doesn't seem to be working.

$ echo "thunk.txt" > src/misc/.mdbookignore
$ echo "my think" > src/misc/thunk.txt
$ ../target/release/mdbook build
 INFO Book building has started
 INFO Running the html backend
 INFO HTML book written to `/Users/michaelhowell/mdBook/guide/book`
$ ls -a book/misc
.			.mdbookignore		thunk.txt
..			contributors.html

It only works when I put it in the root directory.

$ rm -rf book
$ echo "thunk.txt" > src/.mdbookignore
$ ../target/release/mdbook build
 INFO Book building has started
 INFO Running the html backend
 INFO HTML book written to `/Users/michaelhowell/mdBook/guide/book`
$ ls -a book/misc
.			.mdbookignore
..			contributors.html

(If we're not going to implement it, then it shouldn't be a hidden file. Just make it a list of rules in book.toml.)

[Chocorean]

I don't think the point behind this feature request was to have something that mimics exactly what git and other systems do. The point is mdBook has been lacking a simple way to exclude files from its output, for a long time.

I believe that point is addressed here, and the doc explicitly mentions the mdbookignore file lives under src/

[notriddle]

If you don't want to copy Git, then please don't copy Git. I'd prefer if this configuration were stored in the toml file.

[camelid]

@rfcbot concern bespoke interface

I would also prefer this to be simplified by just being a normal entry in the config toml.

[Chocorean]

So be it!
Please allow me a few days, I will move from the .mdbookignore to a config option.
I assume it would live under the [build] configuration ?

[Chocorean]

@GuillaumeGomez @notriddle @camelid Ready for review, moved away from .mdbookignore, now uses a list of globs specified in the config file, under build.ignore

[camelid]

The overall idea seems reasonable to me. I'll leave the code review to Guillaume.

@rustbot reviewed
@rfcbot resolve bespoke interface

[rust-rfcbot]

🔔 This is now entering its final comment period, as per the review above. 🔔

[GuillaumeGomez]

@camelid I'm checking your checkbox as the bot command seems to have miss it.

@Chocorean: Looks all good to me, thanks! Please squash your commits.

[Chocorean]

Ready for take off.

[GuillaumeGomez]

Once the FCP period is done, I'll merge. Thanks. :)

[camelid]

@camelid I'm checking your checkbox as the bot command seems to have miss it.

Ah thanks, I used the wrong bot name.

[rust-rfcbot]

The final comment period, with a disposition to merge, as per the review above, is now complete.

As the automated representative of the governance process, I would like to thank the author for their work and everyone else who contributed.

[GuillaumeGomez]

Thanks everyone!

[DanielEScherzer]

Heads up that CI is probably going to fail, #3250

[GuillaumeGomez]

Let's try again now that #3250 was merged.