Thanks Ondřej and Aaron, for letting me know these points. Yes! markdown files are definitely better. But if we want to go for Markdown then there are better options present. I researched about documenting in Markdown and found some really good SSG (Static Site Generator): Jekyll <https://jekyllrb.com/>
- Simple and easy for developers to work on templates and change the UI. - Easy for Writer to write on Markdown page (or use HTML, CSS in .md file). - Free hosting with Github. Note: - Need to setup Ruby environment and install gem, bunlder for Jekyll. Hugo <https://gohugo.io/> - Fast and simple for developers . - Uses Markdown so it is easy for writers. - Multilingual feature (need to explore about it). - Lot of theme available officially at https://themes.gohugo.io/ - Free hosting with Github. Note: - No need to setup the Go language (Hugo is written in Go). - Simple installation. Docusaurus <https://docusaurus.io/> - Simple and made for documentation only. - Maintained by Facebook and built using React. - Markdown for writing. - Translations using Crowdin <https://crowdin.com/> - Document Versioning feature in built. User can see all versions of your project. - Document Search feature is inbuilt using Algolia. - Free hosting with Github using npm. - Generate Docker related files while creating a project. Note: - Need to setup node and NPM for installation. - I personally feel Javascript frameworks have more features because npm have very useful packages. So if we go for writing documentation with Static site then I think one of the above framework will be good. But I think we need a Documentation processing tool (like for Python we have Sphinx) for SymEngine (so we need a documentation processing tool for Cpp like Doxygen). Please let me know your thoughts on this. P.S.: I see that today is deadline. I just filled the the GSoD form for this project. Thanks and regards, Abhijith MS, Computer Science and Engineering, Purdue University, USA On Fri, 28 Jun 2019 at 03:36, Ondřej Čertík <[email protected]> wrote: > Yes, I would prefer something based on Markdown like mkdocs. > > On Thu, Jun 27, 2019, at 8:40 PM, Aaron Meurer wrote: > > You may want to post this to the SymEngine mailing list as well > https://groups.google.com/forum/#!forum/symengine > > Also be aware that the deadline to apply for GSoD is July 28, which is > tomorrow. > > I don't know the answers to your questions. Ondrej or one of the > SymEngine developers will know for sure, but I suspect Sphinx is > desired for narrative documentation (documentation written directly in > RST, rather than pulled from the code). My guess is that since there > isn't anything existing yet, that they would be open to other tools as > well, if they are better suited. I personally would suggest using > something based on Markdown, but again, Ondrej would be the person to > decide this. > > Aaron Meurer > > On Thu, Jun 27, 2019 at 3:01 AM Abhijith B Vuduthala > <[email protected]> wrote: > > > > > > Hello SymPy and SymEngine team, > > > > My name is Abhijith and I love Open Source projects and would like to > contribute in Documentation of SymPy and SymEngine. I have contributed one > of the GSoC Organization - CloudCV as well. > > > > I was looking into Google Season of Docs program and found the SymPy > Idea description Documentation for SymEngine interesting. I always wanted > to get a chance to contribute to SymPy and GSoD could be good platform. > > > > I have few questions in mind on these points : > > > > The idea description is : > > > > "Create a webpage with documentation. The documentation should be > generated from the source code, probably using Doxygen, and probably > converted to Sphinx. Improve the documentation in the source code to look > nice." > > > > 1. I was going through the SymEngine codebase and I found that docs > folder is completely missing and it is also lacking the comments before > classes and functions. So do we have to create it completely from scratch > or there is some work/PR is already opened? > > > > 2. I have good knowledge of Doxygen and it is really good for C++ > project documentation. But I didn't understand why do we need to convert to > Sphinx. > > > > 3. I see that there are Python, Ruby, Julia wrapper for SymEngine having > different github repository. So documentation for those will be done > separately and it is not the part of this project right? > > > > > > Please let me know your suggestions & share any link of the > discussion(if any related to this project) thread and how do you want to > proceed. Your suggestions and comments will help me to understand the > requirements and deliverables. > > > > Meantime I am exploring the Doxygen tool and codebase of SymEngine to > integrate it. > > > > -- > > Thanks and regards, > > Abhijith > > MS, Computer Science and Engineering, > > Purdue University, USA > > > > > -- Thanks and regards, Abhijith MS, Computer Science and Engineering, Purdue University, USA -- You received this message because you are subscribed to the Google Groups "sympy" group. To unsubscribe from this group and stop receiving emails from it, send an email to [email protected]. To post to this group, send email to [email protected]. Visit this group at https://groups.google.com/group/sympy. To view this discussion on the web visit https://groups.google.com/d/msgid/sympy/CA%2BtXiw9Qf4PGfwDds_1jDGcnC_Gy5cxksbyjGAeOptAiUYE1dQ%40mail.gmail.com. For more options, visit https://groups.google.com/d/optout.
