Docs visual improvement and add documentation guide for new contributor for `docs` #4554

gunungpw · 2022-01-03T08:43:51Z

Detail in issue:

Resolve #4553

this pull request is only for the visual change for docs and update dependency for now
for documentation guide for new contributor, still in progress.
Hope i can help for the new cython 3.0 documentation initiatives,

Link for:

Official Docs
Official Docs theme don't implement mobile view, new sphinx_rtd_theme in testing have good mobile view

Testing Docs

Sorry if my English is not too good, its not my first language

Best Regard,

Gunung P. W.

scoder

I didn't look through all changes, because some seem to lack a motivation. Could you try to explain a bit more what your goals are and why you made certain changes, especially the configuration changes in conf.py? I see a lot of options and code being commented out there now, without an explanation.

Also, all those whitespace and quoting changes make it unnecessarily difficult to see what options were actually changed.

scoder · 2022-01-03T12:06:25Z

docs/index.rst

+:doc:`src/reference/index`
+   How to use Cython to speedup your project.


We are no longer using the reference. It is only left here to keep old links alive.

Thank for info, I will comment out that from :toctree:: and add :orphan: to suppress warning in build time

scoder · 2022-01-03T12:06:42Z

docs/index.rst

+------
+
+:doc:`src/userguide/index`
+   Learn to use Cython package.


Suggested change

Learn to use Cython package.

Learn to use Cython.

This was a placeholder that I add to give context for src/userguide/index link, if the suggestion good I will give it fix.

scoder · 2022-01-03T12:06:51Z

docs/index.rst

+-----------
+
+:doc:`src/quickstart/index`
+   How to install Cython compiler package.


Suggested change

How to install Cython compiler package.

How to install the Cython compiler package.

Thank you 👍 for the fix

scoder · 2022-01-03T12:07:20Z

docs/index.rst

+   How to install Cython compiler package.
+
+:doc:`src/tutorial/index`
+   How to use Cython to speedup your project.


You are using the verb here, not the noun.

Suggested change

How to use Cython to speedup your project.

How to use Cython to speed up your project.

Thank you again, i'm learning new thing

scoder · 2022-01-03T12:08:06Z

docs/index.rst

+   How to contribute changes to Cython.
+
+:doc:`Changelog <src/changes>`
+   Release note of Cython development.


Suggested change

Release note of Cython development.

Release notes for Cython's development.

🛠️ fix

scoder · 2022-01-03T12:18:58Z

docs/README

@@ -1,23 +0,0 @@
-Welcome to Cython's documentation.


Why do you think that this file is no longer useful?

When I remove it, I have a plan to replace it with README.rst that has a new guide for newcomers to edit and build docs locally and link it to docs. But I realize the file has historical value to the project and is already CONTRIBUTING.rst in place for contributing guide. also, my habit to organize project directory give contributing factor. I will revert it back Thanks :)

scoder · 2022-01-03T12:21:00Z

docs/conf.py

+# try: import rst2pdf
+# except ImportError: pass
+# else: extensions.append('rst2pdf.pdfbuilder')


Why did you remove this part?

readthedocs have config for build pdf and epub in .readthedocs.yaml, and i have errors when try to build this locally. I will revert it back if I can't find ways to fix it, or many contributors need to build pdf locally

scoder · 2022-01-03T12:21:50Z

docs/conf.py

-copyright = '%s, %s' % (YEAR, authors)
+project = "Cython"
+authors = "Stefan Behnel, Robert Bradshaw, Dag Sverre Seljebotn, Greg Ewing, William Stein, Gabriel Gellner, et al."
+copyright = f"{YEAR, authors}"


This is not the same.

Thanks, still learning Python

You're close though; f"{YEAR}, {authors}"

scoder · 2022-01-03T12:22:53Z

docs/conf.py

+# except:
+#     pass
+# # The short X.Y version.
+# version = re.sub('^([0-9]+[.][0-9]+).*', '\g<1>', release)


Why did you remove this part?

This is my bad, when build locally I got errors so try to comment block that I don't understand

gunungpw · 2022-01-03T13:17:29Z

Thanks for review.

This PR is just my first try to see if the project docs need update.
For a summary, the change in conf.py is not intended to be permanent, I just want to experiment to see how new landing page in the new theme. for change in .rst file also just for the look in landing page because I still learning reST in linking between page, many part that i add is just for placeholder. Sorry for grammar mistake, i still learning English, hope you can understand. each problem i will address it at a later time. Hope you have a nice day 😄

gunungpw and others added 14 commits January 3, 2022 09:10

remove .hgignore and README

681f1a6

move and rename to docs/docs-requirements.txt

8903cb3

add :orphan: tag

4f8a077

add sphinx-autobuild for auto-reload in local edit

66f6a46

update ToC index.rst

a715d00

add .readthedocs.yaml

c459ceb

update conf.py

017dbb3

fix conf.py and add pdf and epub in rtd config

6ceb155

edit caption

c117acc

fix Parse error in .readthedocs.yaml

4652c58

fix again Parse error in .readthedocs.yaml

f38a9a7

edit out format

10bb900

update index.rst and CONTRIBUTING.rst

98ad411

make logo_only for docs page

c68d0f3

gunungpw mentioned this pull request Jan 3, 2022

[ENH] Pythonise the documentation! #4187

Open

29 tasks

gunungpw changed the title ~~[ECH] Visual improvement and add documentation guide for new contributor~~ Docs visual improvement and add documentation guide for new contributor for docs Jan 3, 2022

scoder reviewed Jan 3, 2022

View reviewed changes

gunungpw and others added 3 commits January 4, 2022 11:09

add banner

4438b45

remove old banner

119dc62

add sphinx-version-warning for banner

1a7f2b1

gunungpw marked this pull request as draft January 4, 2022 06:36

scoder added the Documentation label Jan 6, 2022

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Docs visual improvement and add documentation guide for new contributor for `docs` #4554

Docs visual improvement and add documentation guide for new contributor for `docs` #4554

gunungpw commented Jan 3, 2022 •

edited

Loading

scoder left a comment

scoder Jan 3, 2022

gunungpw Jan 3, 2022

scoder Jan 3, 2022

gunungpw Jan 3, 2022

scoder Jan 3, 2022

gunungpw Jan 3, 2022

scoder Jan 3, 2022

gunungpw Jan 3, 2022 •

edited

Loading

scoder Jan 3, 2022

gunungpw Jan 3, 2022

scoder Jan 3, 2022

gunungpw Jan 3, 2022 •

edited

Loading

scoder Jan 3, 2022

gunungpw Jan 3, 2022

scoder Jan 3, 2022

gunungpw Jan 3, 2022

h-vetinari Jan 5, 2022

scoder Jan 3, 2022

gunungpw Jan 3, 2022

gunungpw commented Jan 3, 2022 •

edited

Loading

		:doc:`src/reference/index`
		How to use Cython to speedup your project.

	How to install Cython compiler package.
	How to install the Cython compiler package.

	How to use Cython to speedup your project.
	How to use Cython to speed up your project.

	Release note of Cython development.
	Release notes for Cython's development.

Docs visual improvement and add documentation guide for new contributor for docs #4554

Are you sure you want to change the base?

Docs visual improvement and add documentation guide for new contributor for docs #4554

Conversation

gunungpw commented Jan 3, 2022 • edited Loading

scoder left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

gunungpw Jan 3, 2022 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

gunungpw Jan 3, 2022 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

gunungpw commented Jan 3, 2022 • edited Loading

Docs visual improvement and add documentation guide for new contributor for `docs` #4554

Docs visual improvement and add documentation guide for new contributor for `docs` #4554

gunungpw commented Jan 3, 2022 •

edited

Loading

gunungpw Jan 3, 2022 •

edited

Loading

gunungpw Jan 3, 2022 •

edited

Loading

gunungpw commented Jan 3, 2022 •

edited

Loading