Merge pull request #2084 from jaimergp/render-markdown-once

Freeze Sphinx content to Markdown

All the RST Sphinx content was rendered as Markdown for Docusaurus. See e7940c0 for the rename mapping.

.ci_scripts/environment.yml

@@ -3,20 +3,6 @@ channels:
   - conda-forge
 dependencies:
   - python=3
-  - conda-smithy
-  - sphinx >=4.4
-  - cloud_sptheme
-  - sphinxcontrib-fulltoc
-  - make
-  - xonsh
-  - myst-parser
-  - pyyaml
-  - jinja2
   - requests
-  - python-dateutil
   - pip
-  - python-rapidjson
-  - termcolor
   - nodejs 20.*
-  - pip:
-    - https://github.com/jaimergp/sphinx-markdown-builder/archive/admonitions.tar.gz

.ci_scripts/generate_cfep_index.py → .ci_scripts/render_templated_content.py

@@ -1,18 +1,25 @@
+import csv
 import re
-import requests
-import sys
 import tarfile
 from dataclasses import dataclass
 from pathlib import Path
 from tempfile import TemporaryDirectory
 
+import requests
+
+
 REPO_URL = "https://github.com/conda-forge/cfep"
 REPO_ARCHIVE = "https://github.com/conda-forge/cfep/archive/main.tar.gz"
 REPO_CONTENTS = "https://api.github.com/repos/conda-forge/cfep/contents/"
 TITLE_PATTERN = "<td>\s*Title\s*</td><td>\s*(.*)\s*</td>"
 STATUS_PATTERN = "<td>\s*Status\s*</td><td>\s*(.*)\s*</td>"
 REPO_DIR = Path(__file__).parents[1].absolute()
-CFEP_INDEX_RST = REPO_DIR / "sphinx" / "src" / "orga" / "cfep-index.rst"
+CFEP_INDEX_MD_TMPL = REPO_DIR / "docs" / "orga" / "cfep-index.md.tmpl"
+CFEP_INDEX_MD = REPO_DIR / "docs" / "orga" / "cfep-index.md"
+GOVERNANCE_MD_TMPL = REPO_DIR / "docs" / "orga" / "governance.md.tmpl"
+GOVERNANCE_MD = REPO_DIR / "docs" / "orga" / "governance.md"
+CORE_CSV = REPO_DIR / "src" / "core.csv"
+EMERITUS_CSV = REPO_DIR / "src" / "emeritus.csv"
 
 
 @dataclass
@@ -93,17 +100,39 @@ def get_cfeps():
 
 
 def write_cfep_index():
-    contents = CFEP_INDEX_RST.read_text()
-    if ".. REPLACE-THIS-LINE-WITH-THE-INDEX-OF-CFEPs" not in contents:
-        print("!!! Skipping writing CFEP index. Already rendered?", file=sys.stderr)
-        return
-    rst_links = [f"- {cfep.rst_link()}" for cfep in get_cfeps()]
+    contents = CFEP_INDEX_MD_TMPL.read_text()
+    md_links = [f"- {cfep.md_link()}" for cfep in get_cfeps()]
+    contents = contents.replace(
+        "{{ cfep_list }}",
+        "\n".join(md_links)
+    )
+    CFEP_INDEX_MD.write_text(contents)
+
+
+def _get_formatted_names(path_file):
+    with open(path_file, "r") as csv_file:
+        dict_csv = csv.DictReader(csv_file)
+        sorted_csv = sorted(dict_csv, key=lambda d: d["name"])
+    return "\n".join(
+        f"- [{m['name']} @{m['github_username']}]"
+        f"(https://github.com/{m['github_username']})" 
+        for m in sorted_csv
+    )
+
+
+def write_core_members():
+    contents = GOVERNANCE_MD_TMPL.read_text()
+    contents = contents.replace(
+        "{{ core_members }}",
+        _get_formatted_names(CORE_CSV)
+    )
     contents = contents.replace(
-        ".. REPLACE-THIS-LINE-WITH-THE-INDEX-OF-CFEPs", 
-        "\n".join(rst_links)
+        "{{ emeritus_members }}",
+        _get_formatted_names(EMERITUS_CSV)
     )
-    CFEP_INDEX_RST.write_text(contents)
+    GOVERNANCE_MD.write_text(contents)
 
 
 if __name__ == "__main__":
     write_cfep_index()
+    write_core_members()

.ci_scripts/update_docs

@@ -12,17 +12,9 @@ if [[ "$CI" == "1" ]]; then
   git checkout -b new_site_content
 fi
 
-pushd "$BASE_DIR/sphinx/src"
-make clean
-rm -rf "$BASE_DIR/static-sphinx"
-# -W --keep-going: list all warnings but fail build in case there are any
-make markdown SPHINXOPTS="-W --keep-going"
-popd
+# Render the templated content (e.g. CFEPs, core.csv, etc)
+python "$BASE_DIR/.ci_scripts/render_templated_content.py"
 
-# Move rendered Sphinx markdown to Docusaurus
-python "$BASE_DIR/.ci_scripts/sphinx_markdown_to_docusaurus.py" "$BASE_DIR/sphinx/src/_build/markdown" docs/
-mkdir -p "$BASE_DIR/static-sphinx/_static"
-cp -r "$BASE_DIR/sphinx/src/_static" "$BASE_DIR/static-sphinx/"
 # Build docusaurus site
 npm install
 npm run build
@@ -31,5 +23,7 @@ npm run build
 # we can't redirect with the Docusaurus plugin, so just copy it
 cp build/news/rss.xml build/docs/news.rss
 
-echo "Built website! Preview at http://localhost:8000 with:"
+set +x
+echo "Built website! Preview with one of:"
 echo "  python -m http.server -d build/"
+echo "  npm run serve"

.github/workflows/meeting-notes.yml

@@ -28,7 +28,7 @@ jobs:
     with:
       date: ${{ inputs.date || 'now' }}
       template_path: misc/DEV_MEETING_TEMPLATE.md
-      output_path: sphinx/src/orga/minutes/%Y-%m-%d.md
+      output_path: docs/orga/minutes/%Y-%m-%d.md
       hackmd_team: conda-forge
       force_push: true
       pr_body: |

.gitignore

@@ -22,14 +22,17 @@ sphinx/newsfeed/demo/_build
 
 # Sphinx output gets moved to Docusaurus' static folder
 /static-sphinx
-/docs
 
 # Docusaurus dependencies
 /node_modules
 
 # Docusaurus production
 /build
 
+# Autogenerated at build time
+/docs/orga/cfep-index.md
+/docs/orga/governance.md
+
 # Generated files
 .docusaurus
 .cache-loader

README.md

@@ -10,20 +10,19 @@ If you have questions or need help, please check out our documentation for a [li
 
 ## Improving the docs
 
-- You can help to improve the documentation! It is version-controlled in the [conda-forge.github.io repository on GitHub](https://github.com/conda-forge/conda-forge.github.io).   The source text is stored in the `sphinx/src/` subdirectory and is formatted using Python’s [reStructuredText system](https://docutils.sourceforge.io/rst.html).
+- You can help to improve the documentation! It is version-controlled in the [conda-forge.github.io repository on GitHub](https://github.com/conda-forge/conda-forge.github.io).
 
 - The docs are built on GitHub Actions and run the `.ci_scripts/update_docs` script.
   We are glad to know that you would like to contribute. To build the docs locally, follow the steps mentioned below:
-1.  [Fork](https://docs.github.com/en/github/getting-started-with-github/fork-a-repo) the [conda-forge.github.io](https://github.com/conda-forge/conda-forge.github.io)        repository to your own GitHub user account.
+
+1.  [Fork](https://docs.github.com/en/github/getting-started-with-github/fork-a-repo) the [conda-forge.github.io](https://github.com/conda-forge/conda-forge.github.io) repository to your own GitHub user account.
 2.  [Clone](https://docs.github.com/en/github/creating-cloning-and-archiving-repositories/cloning-a-repository) this fork onto your computer.
-3.  Go into the main folder. </br>
+3.  Go into the main folder.
     Run the following commands.  
       *  `conda env create -f ./.ci_scripts/environment.yml`
       *  `conda activate conda-forge-docs`
-      *  `cd sphinx`
-      *  `cd newsfeed && pip install --no-deps .`
-      *  `cd ../src`
-      *  `make html`
+      * For live builds, `npm install && npm run start`
+      * For production builds, run `.ci_scripts/update_docs`
 4.  Make and commit your changes.
 5.  Submit a [pull request](https://docs.github.com/en/github/collaborating-with-issues-and-pull-requests/about-pull-requests) to the main repository proposing your changes.
 

sphinx/src/contracting/00_intro.rst → docs/contracting/index.md

@@ -1,46 +1,53 @@
-Contracting Information
-#######################
+---
+title: 'Contracting Information'
+sidebar_position: 28
+---
+
+<a id="contracting-information"></a>
+
+# Contracting Information
 
 If you are interested in a contractual engagement to solve a specific problem that you're facing, this page details the kinds of services that are available to you. conda-forge, as an entity, does not have the ability to engage in a contractual arrangement as of now.
-However, there are a number of community members that you may engage with. 
+However, there are a number of community members that you may engage with.
 conda-forge does not endorse anyone (individuals or companies) listed on this page.
 
-
-If you are interested in a service that is not listed on this page, please reach out to us on our `issue tracker <https://github.com/conda-forge/conda-forge.github.io/issues>`__, on  `Element <https://app.element.io/#/room/#conda-forge:matrix.org>`__  or via emailing the core team directly at conda-forge-core@googlegroups.com and we will help to circulate your request more broadly within the community.
+If you are interested in a service that is not listed on this page, please reach out to us on our [issue tracker](https://github.com/conda-forge/conda-forge.github.io/issues), on  [Element](https://app.element.io/#/room/#conda-forge:matrix.org)  or via emailing the core team directly at [conda-forge-core@googlegroups.com](mailto:conda-forge-core@googlegroups.com) and we will help to circulate your request more broadly within the community.
 
 Our intent with this page is to communicate whom you should contact and negotiate a contract with.
 We hold no liability for the outcome of those negotiations or the results of any work that is done under those terms.
 We will not arbitrate any contract disputes.
 That is between the payer and payee to hammer out on their own.
 
+<a id="known-service-providers"></a>
+
+## Known Service Providers
+
+<a id="lab49"></a>
 
-Known Service Providers
-***********************
+### Lab49
 
-Lab49
-=====
 Services Offered: Architecture and Technical Design Advisory, Cloud Strategy and Migrations, Outsourced Software Development, SDLC Advisory
 
-Contact Information: sales@lab49.com
+Contact Information: [sales@lab49.com](mailto:sales@lab49.com)
 
-Background / Description: Lab49 is a full service strategy, design and technology consultancy with a global reach focused on financial services. We specialize in product development across the full stack, from data and analytics, through services, through next generation user interfaces. 
+Background / Description: Lab49 is a full service strategy, design and technology consultancy with a global reach focused on financial services. We specialize in product development across the full stack, from data and analytics, through services, through next generation user interfaces.
 
+<a id="quansight"></a>
 
-Quansight
-=========
+### Quansight
 
 Services offered: Core Library Development, Data Engineering, Algorithms / AI / ML, Infrastructure / Big Data, Visualization / Dashboards, Open Source Support, Packaging, Integration
 
-Contact Info: https://www.quansight.com/consulting
+Contact Info: [https://www.quansight.com/consulting](https://www.quansight.com/consulting)
 
 Background / Description: Quansight's goal is to create operational solutions to support your analytic and visualization needs. We automate the data-science process in a way that works for your business use cases. Quansight has the experience to assess an organization's needs and provide the best integrated solution to turn raw data into actionable quantitative insights. By employing the maintainers and contributors to many open source projects worldwide, including core aspects of the Conda ecosystem and community, we provide top talent to ensure our customers have access to the latest technology while also leveraging legacy investments.
 
+<a id="becoming-a-service-provider"></a>
 
-Becoming a Service Provider
-***************************
+## Becoming a Service Provider
 
 The conda-forge core team reserves the right to unilaterally update this list at any time for any reason.
 If you are a service provider and are interested in being added to this list please open up a pull request against the conda-forge.github.io repository.
-Add yourself to this list and detailing the services you provide. 
+Add yourself to this list and detailing the services you provide.
 Please be brief and link to existing materials on your own website where possible.
 Then, when ready, ping @conda-forge/core for review and merging.

docs/index.md

@@ -0,0 +1,44 @@
+---
+title: 'conda-forge documentation'
+sidebar_position: 0
+---
+
+<a id="conda-forge-documentation"></a>
+
+# conda-forge documentation
+
+<a id="what-is-conda-forge"></a>
+
+## What is conda-forge?
+
+conda-forge is a community effort and a GitHub organization which contains repositories of conda recipes and thus provides conda packages for a wide range of software.
+The built distributions are uploaded to [anaconda.org/conda-forge](https://anaconda.org/conda-forge) and can be installed with [conda](https://conda.pydata.org/docs/intro.html).
+
+**Missing a package that you would love to install with conda?**
+
+Chances are we have already packaged it for you. You can [search](https://anaconda.org/) for packages online. Look out for packages provided by our `conda-forge` organization.
+
+**Cannot find a package or only outdated versions of a package?** - Everybody is welcome to contribute to our package stack!
+
+- We value all kinds of contributions — not just code. A few recommended ways to start contributing to conda-forge are:
+  - [Contribute new packages](maintainer/adding_pkgs.md)
+  - Help update and [maintain packages](maintainer/updating_pkgs.md)
+  - Suggest or implement improvements for our [infrastructure](maintainer/infrastructure.md)
+  - Help [improve the documentation](user/contributing.md#improve-docs)
+  - For a detailed overview please refer to [Becoming involved](user/contributing.md)
+- To see our governance policies, see [Governance](orga/governance.md).
+- If you find bugs, need help, or want to talk to the developers, use our mailing lists or chat rooms:
+  - [GitHub issues](https://github.com/conda-forge/conda-forge.github.io/issues)
+  - [Element chatroom](https://app.element.io/#/room/#conda-forge:matrix.org)
+  - [Discourse group](https://conda.discourse.group)
+  - [Mailing list (archived)](https://groups.google.com/forum/#!forum/conda-forge)
+
+<a id="table-of-contents"></a>
+
+## Table of Contents
+
+* [User Documentation](user/index.mdx)
+* [Maintainer Documentation](maintainer/index.mdx)
+* [Organisation Documentation](orga/index.mdx)
+* [Miscellaneous](misc/index.md)
+* [Contracting Information](contracting/index.md)