Skip to content

[solidago] init docs content and use mkdocs to build docs pages#1972

Merged
amatissart merged 24 commits intomainfrom
solidago-mkdocs
Mar 29, 2025
Merged

[solidago] init docs content and use mkdocs to build docs pages#1972
amatissart merged 24 commits intomainfrom
solidago-mkdocs

Conversation

@amatissart
Copy link
Member

@amatissart amatissart commented May 16, 2024

Description

Initialize documentation website for Solidago.
The current state is visible on https://solidago.tournesol.app/

Using:

Checklist

  • I added the related issue(s) id in the related issues section (if any)
    • if not, delete the related issues section
  • I described my changes and my decisions in the PR description
  • I read the development guidelines of the CONTRIBUTING.md
  • The tests pass and have been updated if relevant
  • The code quality check pass

@GresilleSiffle GresilleSiffle added the Solidago Tournesol algorithms library label May 23, 2024
@amatissart amatissart force-pushed the solidago-pipeline-docs-1 branch from dde4c9f to 3483609 Compare June 1, 2024 17:53
Base automatically changed from solidago-pipeline-docs-1 to neurips24 June 3, 2024 06:57
Base automatically changed from neurips24 to main October 24, 2024 09:41
@amatissart
Copy link
Member Author

I configured a CNAME DNS record in order to deploy the docs to a custom with Github Pages. For now it needs to be pushed manually with mkdocs gh-deploy but that could also be included in the CI workflows.

The current state is visible on https://solidago.tournesol.app

It's still missing quite a lot of docstrings, it needs a little more polish here and there, and more examples would also be helpful.

@lenhoanglnh What is your opinion about the structure of the docs? Are there specific sections to create in order to help onboard researchers?

@amatissart amatissart marked this pull request as ready for review March 26, 2025 17:53
@amatissart
Copy link
Member Author

I think this PR is ready to be merged now. The docs are visible on https://solidago.tournesol.app/

@GresilleSiffle @lenhoanglnh Do you want to have a look before I merge?

@GresilleSiffle
Copy link
Collaborator

It looks very good to me @amatissart 👌

Feel free to merge when you want, maybe after a review from @lenhoanglnh

In the future the Get Started page could benefit from more paragraphs, to help the users understand what are the goals of Solidago and in which context the library is relevant. If I understood correctly, this PR is the initial set-up of the documentation, not an effort to document everything exhaustively right?

Very minor for now: some functions use a prescriptive form of docstring, as recommended by PEP257 (like "Standardize scores..."), whereas other use a descriptive form (like "Aggregates the scores..."). We could decide which form we want to use in the doc.

@GresilleSiffle
Copy link
Collaborator

An idea: we could add a link to the documentation in the footer of the front end, under the section Research.

@amatissart
Copy link
Member Author

An idea: we could add a link to the documentation in the footer of the front end, under the section Research.

Done in 5d93da4

@amatissart amatissart merged commit cf302fe into main Mar 29, 2025
6 checks passed
@amatissart amatissart deleted the solidago-mkdocs branch March 29, 2025 18:35
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

Solidago Tournesol algorithms library

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants