Add a documentation for the blog.yml feature #2796
Merged
Conversation
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
3 tasks
Florian3k
reviewed
May 11, 2023
Florian3k
added a commit
to scala/scala3
that referenced
this pull request
May 11, 2023
- Add input config, who allow to define the path import - Add output config, who allow to define the path destination - Add hidden, who allow to not generate the blog Should I add warnings? For example when the path is not found. If so, how do I test? Because the path is searched for _blog but it is not found so the assert that asks for no warnings does not work as in [this one](https://github.com/lampepfl/dotty/blob/d4a86000404cd3bb774025d48151c6311d6bc96d/scaladoc/test/dotty/tools/scaladoc/ReportingTest.scala#L73). Here is my proposal to add a blog configuration using a .yaml in the same place as the sidebar.yaml. This [feature](#14487) request is a bit old but I thought it would be interesting to create it to give a bit more flexibility to Scaladoc users. This first PR allows me to validate with you if this feature is good to implement and also to have some feedbacks I answer well to what is asked and that my code is relevant. So if it is the case, I will do the tests and the associated documentation. ### TO-DO list: - [x] First version of the code - [x] Add documentation Will be implemented in docs.scala-lang, [PR #2796](scala/docs.scala-lang#2796): *** ### Blog Configuration Documentation Blog configuration is an important aspect of any blog platform. In order to customize the configuration of a blog, it is often necessary to modify the default settings. In this document, we will explain how to change the default config of a blog documentation with a file blog.yaml. In order to modify the default settings of the blog documentation, users need to create a file named "blog.yaml" in the root directory of the blog. The file should contain the parameters that the user wants to change. For example, if a user wants to change the input directory to "my_posts", the output directory to "my_docs", and temporarily hide the blog, they can create a file with the following content: `blog.yaml:` ``` input: my_posts output: my_docs hidden: true ``` Parameters: The blog.yaml file is a configuration file that allows users to modify the default settings of their blog documentation. The following parameters can be configured in the blog.yaml file: input: This parameter specifies the directory where the markdown pages and other files will be taken for the blogs page. By default, this is set to the "_posts" folder in the "docs" directory of the blog. However, users can change this to any other directory in "docs". output: This parameter specifies the folder where the HTML pages will be generated. By default, this is set to the "blog" folder in the "target/docs" directory. However, users can change this to any other directory on "target/docs". hidden: This parameter allows users to hide or unhide the blog temporarily. By default, this is set to "false", which means that the blog is visible to all users. However, if a user wants to temporarily hide the blog, they can set this parameter to "true". This can be useful if the user wants to make some changes to the blog and doesn't want anyone to see the changes until they are ready. Once the file is created, the user needs to save it in the root directory of the blog. The next time the blog is built, the new settings will be applied. *** - [x] Add tests ## Example (Success) ### Code & Input <img width="328" alt="Screenshot 2023-04-06 at 14 41 47" src="https://user-images.githubusercontent.com/44496264/230382241-9433d641-03ec-4495-8fd2-81fa6ce3bc17.png"> <img width="329" alt="Screenshot 2023-04-06 at 14 41 58" src="https://user-images.githubusercontent.com/44496264/230382414-7876c601-b1f0-498f-85e1-71ecc500cf09.png"> ### Result <img width="326" alt="Screenshot 2023-04-06 at 14 42 09" src="https://user-images.githubusercontent.com/44496264/230382463-9fe234ac-3fd0-4d56-a04c-6f6deb01a308.png"> ## First example (Hidden) ### Code <img width="254" alt="Screenshot 2023-04-06 at 14 46 27" src="https://user-images.githubusercontent.com/44496264/230382770-7aabf9a2-e46f-429d-b1c9-97892072349a.png"> ### Result <img width="335" alt="Screenshot 2023-04-06 at 14 42 36" src="https://user-images.githubusercontent.com/44496264/230383192-05e0187f-5ecf-4bd9-8697-122093577d43.png"> <img width="316" alt="Screenshot 2023-04-06 at 14 42 47" src="https://user-images.githubusercontent.com/44496264/230382928-8130cddd-f8dd-4b43-bee1-15129af308c8.png"> ## Example (Error) <img width="316" alt="Screenshot 2023-04-06 at 14 43 03" src="https://user-images.githubusercontent.com/44496264/230383219-ff6844e2-47c5-40d6-9056-a8ab1dc6f8e6.png"> <img width="945" alt="Screenshot 2023-04-06 at 14 43 14" src="https://user-images.githubusercontent.com/44496264/230383236-2ee07f63-640c-4bc1-a3b1-e0785ff467e9.png"> Fixes: #14487
Dedelweiss
changed the title
Dedelweiss
force-pushed
the
documentation-blog-settings
branch
from
c94f911 to
34022d7
Compare
Florian3k
approved these changes
May 12, 2023
|
cc @SethTisue |
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
The goal of this PR is to add a documentation for the new feature "Settings configuration with the blog.yml".
Related to the PR on Dotty: scala/scala3#17214