diff --git a/docs/_toc.yml b/docs/_toc.yml index b2fd828..0dccd84 100644 --- a/docs/_toc.yml +++ b/docs/_toc.yml @@ -11,9 +11,9 @@ parts: - file: notebooks/bibliography.ipynb - caption: Recommended Workflows chapters: - - file: docs/good-practices - - file: docs/general-guide + - file: docs/folders-and-naming - file: docs/git-workflows + - file: docs/notebook-workflows - caption: Gallery chapters: - file: docs/gallery diff --git a/docs/folders-and-naming.md b/docs/folders-and-naming.md index 4c622cf..d6fd0b6 100644 --- a/docs/folders-and-naming.md +++ b/docs/folders-and-naming.md @@ -22,16 +22,4 @@ We recognize that this approach may create some duplication and additional effor ## Programming Environments - **Python virtual environments.** We recommend using ```.venv``` for virtual environments. This allows for automatic detection by tools and editors like VS Code, simplifies setup, and keeps the folder hidden in most operating systems, reducing clutter. It also promotes consistency across projects, making it easier for others to understand and navigate your setup. because this keeps the folder tree clean among other advantages. -- **Environment file for secrets and credentials**. In the project folder, you will find a file ```.env.example```, rename that file to ```.env```. This is what you will to keep API keys and other secrets. Again, refer to [this part](https://worldbank.github.io/template/README.html) of the documentation for details. - - - - - - - - - - - - +- **Environment file for secrets and credentials**. In the project folder, you will find a file ```.env.example```, rename that file to ```.env```. This is what you will to keep API keys and other secrets. Again, refer to [this part](https://worldbank.github.io/template/README.html) of the documentation for details. \ No newline at end of file diff --git a/docs/git-workflows.md b/docs/git-workflows.md index eb569fd..5b0bd3d 100644 --- a/docs/git-workflows.md +++ b/docs/git-workflows.md @@ -1,7 +1,6 @@ # Guidelines for Git and GitHub Workflows This section provides essential guidelines for using Git and GitHub effectively, ensuring a structured and collaborative workflow for all team members in a project. By following these practices—such as consistently ignoring the "data" folder to protect sensitive information, avoiding direct pushes to the main branch, creating descriptive branch names, and submitting pull requests once work on a branch is complete—we can maintain a clean, organized codebase and promote efficient collaboration. These guidelines help uphold version control best practices, streamline teamwork, and reduce the potential for errors in project repositories. - ## Branch Names and Other General Practices - **Branch names**. After joining the project and cloning the repository, create a concise, descriptive branch name for your work and ensure you switch to that branch before beginning any work on your machine. - **Update branches**. Avoid creating new update branches; instead, push your changes and resolve any conflicts directly. For instance, if bots in the repository modify your code (e.g., adjusting indentations), simply pull these changes before pushing your own updates. @@ -9,13 +8,8 @@ This section provides essential guidelines for using Git and GitHub effectively, ## Folders and Files to Ignore As all data science repos in the Data Lab use this template, the project repo will come with ```.ignore``` file prepopulated with most files and folders which need to be ignored. However, once you join the project and create your own branch. You will have to make sure that the following folders are being ignored. -- Data folder + +- Data folder - Virtual environments (```.venv```) - Environment (```.env```) -Feel free to add any other files (e.g., system files specific to your OS) to the ```.gitignore``` - - - - - - +Feel free to add any other files (e.g., system files specific to your OS) to the ```.gitignore``` \ No newline at end of file diff --git a/docs/good-practices.md b/docs/good-practices.md deleted file mode 100644 index 32e7b64..0000000 --- a/docs/good-practices.md +++ /dev/null @@ -1,11 +0,0 @@ -# Recommended Workflows for Data Science Project -In this series of documents, we present what we consider best practices for executing data science projects. It’s important to note that these practices are tailored specifically to the work of the Data Lab. While they may not be universally applicable to all data science projects, we believe they remain highly valuable. - -These documents will cover the following topics: - -1.**Git and GitHub Workflow Standards and Guidelines** - -2.**Guidelines for Communicating and Presenting Data Outputs.** - -3.**Standards for Documenting and Styling Analytical Notebooks** - diff --git a/docs/notebooks-workflows.md b/docs/notebooks-workflows.md index 9a7bed8..59e995c 100644 --- a/docs/notebooks-workflows.md +++ b/docs/notebooks-workflows.md @@ -3,8 +3,4 @@ This section provides best practices for structuring analytical notebooks to enh - **Structure**. In all the Data Lab projects, please follow [this analytics structure](https://github.com/worldbank/sudan-poverty-monitoring/blob/main/docs/2-analytics.md). - **Editing _toc.yml** -- **Removing/hiding cell blocks** All notebooks will be rendered in Jupyter Book. To enhance readability, ensure code cells are hidden or removed using cell tags. In some cases, you may use the hide-input cell tag. - - - - +- **Removing/hiding cell blocks** All notebooks will be rendered in Jupyter Book. To enhance readability, ensure code cells are hidden or removed using cell tags. In some cases, you may use the hide-input cell tag. \ No newline at end of file