Add docs portal

[almog-lv]

User description

Added documentation portal

---

Type

enhancement, documentation

---

Description

• Added a new CI workflow for automatically deploying documentation updates to GitHub Pages.
• Customized the appearance of the documentation site with primary and accent colors, and adjusted font sizes.
• Created comprehensive documentation for the AlphaCodium project, including an abstract, installation guide, usage instructions, technical Q&A, and broader applicability insights.
• Configured MkDocs with a custom theme, navigation, social links, and Markdown extensions for an enhanced documentation experience.
• Customized the footer of the documentation site with CodiumAI branding and social links.

---

Changes walkthrough

	Relevant files
Configuration changes	ci.yml Add Continuous Integration Workflow for Documentation Deployment .github/workflows/ci.yml Added a new CI workflow named docs-ci for deploying documentation. Configures Git credentials and sets up Python with dependencies for building the docs. Utilizes mkdocs gh-deploy for deploying the documentation to GitHub Pages. +30/-0    mkdocs.yml Configure MkDocs for AlphaCodium Documentation Site            docs/mkdocs.yml Configured site name, navigation, theme, and plugins for the MkDocs site. Customized theme palette and added social links. Included custom CSS for styling and various Markdown extensions for enhanced documentation features. +91/-0
Enhancement	custom.css Customize Documentation Site Appearance                                    docs/docs/css/custom.css Customized primary and accent colors for the documentation site. Adjusted font sizes for navigation titles, links, and header titles. +15/-0    footer.html Customize Footer for Documentation Site                                    docs/overrides/partials/footer.html Customized the footer with CodiumAI branding and social links. Styled the footer to match the documentation site's theme. +100/-0
Documentation	index.md Create Comprehensive Documentation for AlphaCodium Project docs/docs/index.md Introduced the AlphaCodium project with an abstract, installation guide, and usage instructions. Added technical Q&A, broader applicability insights, and an example problem to demonstrate the project's capabilities. Provided acknowledgments and citation information. +232/-0

---

✨ PR-Agent usage:
Comment /help on the PR to get a list of all available PR-Agent tools and their descriptions

[qodo-merge-pro]

PR-Agent was enabled for this repository. To use it, please link your git user with your CodiumAI identity here.

PR Description updated to latest commit (c0e4bde)

• Copy walkthrough table to "Files Changed" Tab

[qodo-merge-pro]

PR-Agent was enabled for this repository. To use it, please link your git user with your CodiumAI identity here.

PR Review

⏱️ Estimated effort to review [1-5]	4, because the PR introduces a significant amount of documentation, configuration changes for CI/CD, and custom styling for the documentation portal. Reviewing this PR requires understanding the documentation content for accuracy, ensuring the CI/CD pipeline is correctly set up for deploying documentation, and verifying the custom styling aligns with the project's branding and usability standards.
🧪 Relevant tests	No
🔍 Possible issues	Possible Bug: The CI workflow does not include a step for installing project-specific dependencies other than mkdocs-material. If the documentation build process requires other dependencies, the CI job may fail.
	Styling Concern: The custom CSS and footer HTML customization are hardcoded with specific color values and layout configurations. This might limit the flexibility to easily change the theme or color scheme in the future without directly modifying these files.
	Missing Newline: The .github/workflows/ci.yml file does not end with a newline. While this is not a critical issue, it is a common practice to end files with a newline for better compatibility across different systems and editors.
🔒 Security concerns	No

---

✨ Review tool usage guide:

---

Overview:
The review tool scans the PR code changes, and generates a PR review. The tool can be triggered automatically every time a new PR is opened, or can be invoked manually by commenting on any PR.
When commenting, to edit configurations related to the review tool (pr_reviewer section), use the following template:

/review --pr_reviewer.some_config1=... --pr_reviewer.some_config2=...

With a configuration file, use the following template:

[pr_reviewer]
some_config1=...
some_config2=...

Utilizing extra instructions The review tool can be configured with extra instructions, which can be used to guide the model to a feedback tailored to the needs of your project. Be specific, clear, and concise in the instructions. With extra instructions, you are the prompter. Specify the relevant sub-tool, and the relevant aspects of the PR that you want to emphasize. Examples for extra instructions: [pr_reviewer] # /review # extra_instructions=""" In the 'possible issues' section, emphasize the following: - Does the code logic cover relevant edge cases? - Is the code logic clear and easy to understand? - Is the code logic efficient? ... """ Use triple quotes to write multi-line instructions. Use bullet points to make the instructions more readable.

How to enable\disable automation When you first install PR-Agent app, the default mode for the review tool is: pr_commands = ["/review", ...] meaning the review tool will run automatically on every PR, with the default configuration. Edit this field to enable/disable the tool, or to change the used configurations

Auto-labels The review tool can auto-generate two specific types of labels for a PR: a possible security issue label, that detects possible security issues (enable_review_labels_security flag) a Review effort [1-5]: x label, where x is the estimated effort to review the PR (enable_review_labels_effort flag)

Extra sub-tools The review tool provides a collection of possible feedbacks about a PR. It is recommended to review the possible options, and choose the ones relevant for your use case. Some of the feature that are disabled by default are quite useful, and should be considered for enabling. For example: require_score_review, require_soc2_ticket, and more.

Auto-approve PRs By invoking: /review auto_approve The tool will automatically approve the PR, and add a comment with the approval. To ensure safety, the auto-approval feature is disabled by default. To enable auto-approval, you need to actively set in a pre-defined configuration file the following: [pr_reviewer] enable_auto_approval = true (this specific flag cannot be set with a command line argument, only in the configuration file, committed to the repository) You can also enable auto-approval only if the PR meets certain requirements, such as that the estimated_review_effort is equal or below a certain threshold, by adjusting the flag: [pr_reviewer] maximal_review_effort = 5

More PR-Agent commands To invoke the PR-Agent, add a comment using one of the following commands: /review: Request a review of your Pull Request. /describe: Update the PR title and description based on the contents of the PR. /improve [--extended]: Suggest code improvements. Extended mode provides a higher quality feedback. /ask <QUESTION>: Ask a question about the PR. /update_changelog: Update the changelog based on the PR's contents. /add_docs 💎: Generate docstring for new components introduced in the PR. /generate_labels 💎: Generate labels for the PR based on the PR's contents. /analyze 💎: Automatically analyzes the PR, and presents changes walkthrough for each component. See the tools guide for more details. To list the possible configuration parameters, add a /config comment.

See the review usage page for a comprehensive guide on using this tool.

[qodo-merge-pro]

PR Code Suggestions

Category	Suggestions
Enhancement	Use semantic HTML for better accessibility and SEO. Consider using semantic HTML elements to improve accessibility and SEO. For example, instead of using for the footer links and social icons, use for navigation links and with for listing the social icons. This change enhances the semantic meaning of the content and helps screen readers and search engines better understand the structure of your webpage. docs/overrides/partials/footer.html [71-93] -<div class="footer-links"> - <a href="URL_TO_CODIUMATE">Codiumate</a> - <p>|</p> - <a href="URL_TO_ALPHACODIUM">PR-Agent</a> -</div> -<div class="social-icons"> +<nav class="footer-links"> + <ul> + <li><a href="URL_TO_CODIUMATE">Codiumate</a></li> + <li><a href="URL_TO_ALPHACODIUM">PR-Agent</a></li> + </ul> +</nav> +<nav class="social-icons"> + <ul> + <li><a href="https://github.com/Codium-ai" target="_blank" rel="noopener" title="github.com" class="social-link">...</a></li> + <!-- Other social links --> + </ul> +</nav>
	Add descriptions for navigation items. For better accessibility and user experience, consider adding a description for each navigation item in the nav section. This helps users understand the content of the linked page before clicking on it. docs/mkdocs.yml [3-4] nav: - - AlphaCodium: 'index.md' + - AlphaCodium: + - Home: 'index.md' + - Installation: 'installation.md' + - Usage: 'usage.md' + - FAQ: 'faq.md'
Security	Add noreferrer to external links for security. Ensure external links have noopener noreferrer in the rel attribute to improve security. This prevents the newly opened page from having control over the original page which mitigates potential security risks. docs/overrides/partials/footer.html [70] -<a href="https://www.codium.ai/" target="_blank" rel="noopener">CodiumAI</a> +<a href="https://www.codium.ai/" target="_blank" rel="noopener noreferrer">CodiumAI</a>
Best practice	Move CSS to an external stylesheet for better maintainability. For better maintainability and separation of concerns, consider moving the CSS styles to an external stylesheet. This approach makes the HTML file cleaner and the styles easier to manage, especially for larger projects. docs/overrides/partials/footer.html [7-64] -<style> - body { - margin: 0; - padding: 0; - font-family: Arial, sans-serif; - font-size: 16px; - } - ... -</style> +<!-- Link to external CSS file --> +<link rel="stylesheet" href="path/to/your/stylesheet.css">
	Acknowledgment of using HTML5 semantic elements. To ensure the website is future-proof and maintains compatibility with evolving web standards, consider using HTML5 semantic elements like for the footer section. This enhances the semantic meaning and accessibility of the content. docs/overrides/partials/footer.html [68] -<footer class="wrapper"> +<!-- No change needed, this is an acknowledgment of good practice -->
	Use relative links for internal resources. Consider using relative links for internal resources to ensure the documentation is accessible even if the repository's URL changes or it is accessed from a different domain. This applies to the links to the paper, dataset, and images within the repository. docs/docs/index.md [5-23] -[Paper](https://arxiv.org/abs/2401.08500) | -[Dataset](https://huggingface.co/datasets/talrid/CodeContests_valid_and_test_AlphaCodium/blob/main/codecontests_valid_and_test_processed_alpha_codium.zip) - +[Paper](../papers/2401.08500.pdf) | +[Dataset](../datasets/codecontests_valid_and_test_processed_alpha_codium.zip) +
	Add a step to check for broken links in the documentation. To ensure the CI pipeline is more robust, consider adding a step to check for broken links in the documentation. This can be done using a tool like mkdocs with the mkdocs-linkcheck plugin or a similar tool. .github/workflows/ci.yml [30] +- run: pip install mkdocs-linkcheck +- run: mkdocs build --site-dir site +- run: mkdocs-linkcheck site - run: mkdocs gh-deploy -f docs/mkdocs.yml --force
Accessibility	Add aria-label to links for improved accessibility. To enhance the website's accessibility, consider adding aria-label attributes to the navigation links. This provides screen readers with a context of the link's purpose, improving the experience for users relying on assistive technologies. docs/overrides/partials/footer.html [77-93] -<a href="https://github.com/Codium-ai" target="_blank" rel="noopener" title="github.com" class="social-link"> +<a href="https://github.com/Codium-ai" target="_blank" rel="noopener" title="github.com" class="social-link" aria-label="Visit our GitHub">
Readability	Break down instructions into smaller, numbered sections. To enhance readability and maintainability, consider breaking down the installation and how-to-run instructions into smaller, numbered sections or bullet points. This will make it easier for users to follow the steps. docs/docs/index.md [28-34] -1. setup a virtual environment and run: `pip install -r requirements.txt` -2. Duplicate the file `alpha_codium/settings/.secrets_template.toml`, rename it as `.secrets.toml`, and fill in your OpenAI API key: +- **Setup a virtual environment:** + 1. Run: `pip install -r requirements.txt` +- **Configure API key:** + 1. Duplicate the file `alpha_codium/settings/.secrets_template.toml` + 2. Rename it as `.secrets.toml` + 3. Fill in your OpenAI API key
Maintainability	Use CSS variables for common values. To ensure the custom styles are easily maintainable and scalable, consider using CSS variables for common values such as font sizes. This allows for easier updates and consistency across the stylesheet. docs/docs/css/custom.css [5-14] +:root { + --font-size-nav: 16px; + --font-size-header: 20px; +} .md-nav__title, .md-nav__link { - font-size: 16px; /* Adjust the font size as needed */ + font-size: var(--font-size-nav); } .md-tabs__link { - font-size: 16px; /* Adjust the font size as needed */ + font-size: var(--font-size-nav); } .md-header__title { - font-size: 20px; /* Adjust the font size as needed */ + font-size: var(--font-size-header); }

---

✨ Improve tool usage guide:

---

Overview:
The improve tool scans the PR code changes, and automatically generates suggestions for improving the PR code. The tool can be triggered automatically every time a new PR is opened, or can be invoked manually by commenting on a PR.
When commenting, to edit configurations related to the improve tool (pr_code_suggestions section), use the following template:

/improve --pr_code_suggestions.some_config1=... --pr_code_suggestions.some_config2=...

With a configuration file, use the following template:

[pr_code_suggestions]
some_config1=...
some_config2=...

Enabling\disabling automation When you first install the app, the default mode for the improve tool is: pr_commands = ["/improve --pr_code_suggestions.summarize=true", ...] meaning the improve tool will run automatically on every PR, with summarization enabled. Delete this line to disable the tool from running automatically.

Utilizing extra instructions Extra instructions are very important for the improve tool, since they enable to guide the model to suggestions that are more relevant to the specific needs of the project. Be specific, clear, and concise in the instructions. With extra instructions, you are the prompter. Specify relevant aspects that you want the model to focus on. Examples for extra instructions: [pr_code_suggestions] # /improve # extra_instructions=""" Emphasize the following aspects: - Does the code logic cover relevant edge cases? - Is the code logic clear and easy to understand? - Is the code logic efficient? ... """ Use triple quotes to write multi-line instructions. Use bullet points to make the instructions more readable.

A note on code suggestions quality While the current AI for code is getting better and better (GPT-4), it's not flawless. Not all the suggestions will be perfect, and a user should not accept all of them automatically. Suggestions are not meant to be simplistic. Instead, they aim to give deep feedback and raise questions, ideas and thoughts to the user, who can then use his judgment, experience, and understanding of the code base. Recommended to use the 'extra_instructions' field to guide the model to suggestions that are more relevant to the specific needs of the project, or use the custom suggestions 💎 tool With large PRs, best quality will be obtained by using 'improve --extended' mode.

More PR-Agent commands To invoke the PR-Agent, add a comment using one of the following commands: /review: Request a review of your Pull Request. /describe: Update the PR title and description based on the contents of the PR. /improve [--extended]: Suggest code improvements. Extended mode provides a higher quality feedback. /ask <QUESTION>: Ask a question about the PR. /update_changelog: Update the changelog based on the PR's contents. /add_docs 💎: Generate docstring for new components introduced in the PR. /generate_labels 💎: Generate labels for the PR based on the PR's contents. /analyze 💎: Automatically analyzes the PR, and presents changes walkthrough for each component. See the tools guide for more details. To list the possible configuration parameters, add a /config comment.

See the improve usage page for a more comprehensive guide on using this tool.